In an OData metadata document, how does a vocabulary annotation apply a term to a model element, and what does Core.Computed tell a client?

## Vocabularies, terms and annotations OData metadata is extensible through **vocabularies**. A vocabulary is a CSDL schema that contains **terms**; each term is a named metadata extension with a type. An **annotation** applies a term to a model element (a schema, an entity type, a property, an entity set, an action or function, a parameter) and supplies the value of that application. The OData technical committee publishes shared vocabularies, among them **Core** (`Org.OData.Core.V1`, usually aliased `Core`) and **Capabilities** (`Org.OData.Capabilities.V1`), and anyone can define a vocabulary for a scenario of their own. ## Bringing a vocabulary into scope Both the term and the annotated element MUST be in scope. A metadata document references the vocabulary's CSDL document and includes its namespace: - in CSDL XML, `edmx:Reference Uri="..."` containing `edmx:Include Namespace="Org.OData.Core.V1" Alias="Core"`; - in CSDL JSON, a `$Reference` entry whose `$Include` lists `$Namespace` and `$Alias`. The alias is a document-local shorthand, so `Core.Description` and `Org.OData.Core.V1.Description` name the same term. ## Applying a term: term, target, value, qualifier 1. **Term**: `Term="Core.Description"` in XML, or a member named `"@Core.Description"` in JSON. 2. **Target**: implicit, by nesting the annotation inside the element it annotates, or explicit through **external targeting**: an XML `Annotations Target="Sales.Customer"` block, or a JSON `$Annotations` member keyed by the target path. External targeting lets an annotation live in a different schema, or a different document, from the element it describes. 3. **Value**: a constant expression (`String="..."`, `Bool="false"`) or a dynamic one such as a `Path` to a property. With no expression, a term of primitive type evaluates to the term's `DefaultValue`. 4. **Qualifier**: an optional simple identifier (`Qualifier="Tablet"`, or `#Tablet` in JSON) so that one term can be applied several times to the same element. Target, term and qualifier together identify exactly one annotation, and an element MUST NOT carry two annotations with the same term and qualifier. A term's definition may list where it applies (`AppliesTo`), but clients SHOULD be prepared for any term on any element. ## Core terms a client acts on Many Core terms have the type `Core.Tag`, a Boolean whose `DefaultValue` is `true`, so a bare `<Annotation Term="Core.Computed"/>` means true. | Core term | Applies to | What it tells a client | |---|---|---| | `Description`, `LongDescription` | most elements | human-readable text for documentation and tooltips | | `Computed` | property | the value is generated on both insert and update | | `Immutable` | property | a client may supply the value on insert; it remains unchanged on update | | `Permissions` | properties, types, entity sets, operations | flags `None`, `Read`, `Write`, `ReadWrite`, `Invoke` | | `OptimisticConcurrency` | entity set | data modification requires ETags; lists the properties the ETag is computed from | | `SchemaVersion` | schema, reference | the version of a schema, for version-specific requests | The protocol gives `Computed` teeth. When an entity is created, computed properties can be omitted and MUST be ignored if included. On update, key and read-only properties, computed ones included, can be omitted, and a value sent for one MUST be ignored. A generated form should therefore show computed fields as read-only rather than let users type values that silently vanish. ## Rules that keep annotations safe - A service MUST NOT require a client to understand custom annotations to interpret a response, and the minimal conformance level forbids requiring clients to understand any metadata or instance annotations. - Clients SHOULD ignore unknown or invalid terms and treat invalid values as unknown; such annotations should never cause an error while the payload stays well formed. - An **instance annotation** in a payload overrides the same annotation made in metadata. - A derived type's annotation replaces, rather than merges with, its base type's annotation for the same term and qualifier. - A client can state which annotations it wants with the `odata.include-annotations` preference, which applies to metadata requests as well as data; the service MAY ignore it.