--- id: terminology slug: /apis/conventions/terminology title: 'Terminology' description: 'Asset, asset type, asset state, attribute definition and Oid — the five terms the Agility API vocabulary is built from.' sidebar_label: 'Terminology' sidebar_position: 6 tags: ['api', 'conventions', 'terminology', 'assets', 'oid'] --- Five terms carry most of the weight in the Agility API. Everything else is built from them. ## Asset A **system asset** is a core business object in the Agility (formerly VersionOne Lifecycle) model. Assets represent the stories and backlog items, defects, sprints and iterations, and the members who use the system. Every read and write in the API is ultimately an operation on assets. See [Assets](/concepts/assets) for the conceptual treatment. ## Asset Type Asset types describe the "classes" of data available. Each asset type carries a collection of attribute definitions, a collection of operations, and metadata such as a default sort order. Asset types form an **inheritance hierarchy**: each type inherits attribute definitions, operations and rules from its parent. Types at the leaves of the hierarchy are **concrete**; types with children are **abstract**. Every asset is an instance of a concrete type. For example, `Story` and `Defect` are concrete asset types. `Workitem` is abstract, and both `Story` and `Defect` ultimately derive from it. Querying `Workitem` therefore returns both. ### System Names Versus UI Names Most asset types share a name with the application UI — a Defect in the UI is a `Defect` asset type. But several of the most common types do not, because the UI name is configurable per methodology while the system name is fixed: | System name | XP | Scrum | AgileUP | DSDM | | ------------ | --------- | ------------- | ----------- | ------------- | | `Scope` | Project | Project | Project | Project | | `ScopeLabel` | Project | Project | Project | Project | | `Story` | Story | Backlog Item | Requirement | Requirement | | `Timebox` | Iteration | Sprint | Iteration | Iteration | | `Theme` | Theme | Feature Group | Use Case | Feature Group | **Always use the system name in API calls.** The UI-facing name is a localized display value; resolve it through [`loc-2.v1`](/apis/loc-2-v1) if you need to render it. ## Asset State Asset states represent the system-known lifecycle stage of an asset. It is a numeric attribute (`AssetState`), and the UI typically shows only assets that are not "dead". Dead is a range, not a single value: every state of `192` or above is dead, and `192` itself is never stored. | State | Name | Meaning | | ----- | ------------------- | ------------------------------------------------------------------ | | `0` | Future | The asset exists but has not been activated. | | `64` | Active | The asset has been assigned to a user-defined workflow status. | | `128` | Closed | The asset has been closed or quick-closed. | | `200` | Template (dead) | Used only to create new copies via Templates or Quick Add. | | `208` | Broken Down (dead) | The asset was converted to an Epic for further break-down. | | `209` | Collaborator (dead) | Members only: a guest collaborator, not a full member. | | `254` | Deprecated (dead) | Retired by the system, such as subscriptions to a removed feature. | | `255` | Deleted (dead) | The asset has been deleted. | :::note Deletion is not erasure Deleted assets are not permanently removed. They are marked with an asset state indicating they have no further value to the system. If an asset is significant or has historical importance, consider **closing** it when it reaches maturity rather than deleting it. ::: This is why almost every real-world filter carries a clause like `AssetState!='255'` — without it you get the tombstones back too. Filters on `AssetState` match bands rather than exact values, and `AssetState!='128'` means "below Closed", so it also excludes dead and deleted assets. See [AssetState values](/reference/attribute-types#assetstate-values) before filtering on it. ## Attribute Definition Attribute definitions describe the properties that make up each asset type. Each one declares the type of data it holds and whether it is required, read-only, multi-value, and more. Attribute definition names are unique within their asset type. An attribute definition is either a **value type** (a scalar) or a **relation** to other assets. Relations are further either single-value or multi-value: - `Estimate` on `Workitem` is a scalar — specifically a number. - `Scope` on `Workitem` is a **single-value relation** to a `Scope` asset. - `Workitems` on `Scope` is the reciprocal **multi-value relation** back to `Workitem` assets. Discover the full set for any type through [`meta.v1`](/apis/meta-v1). Compose them into paths using the [attribute definition syntax](/apis/conventions/attribute-definitions). ## Oid An **Oid** is a unique system identifier, not normally visible in the Agility user interface. An **Oid token** is the string form: the asset type name and an integer ID joined by a colon. ```text Member:20 Story:1220 Scope:0 ``` `Scope:0` is the system root project and is a useful anchor in examples. An Oid token may carry a third segment identifying a specific **moment** — a historical version of the asset: ```text Story:1220:4471 ``` An Oid is **not** the same as the user-visible `Number` attribute (`S-01047`, `D-00234`), which is available on many but not all assets and is meant for humans. ## Related Topics - [Glossary](/reference/glossary) — alphabetical quick reference for these and other terms - [Assets](/concepts/assets), [Attributes](/concepts/attributes), [Relations](/concepts/relations) - [Metadata API (meta.v1)](/apis/meta-v1) — discover asset types and attribute definitions at runtime