Aster Web Data / Reference

AsterData vocabulary

The AsterData annotations and functions.

Annotations

The vocabulary is Aster.Data.V1, with the alias AsterData. It is published in $metadata and at /vocabularies/Aster.Data.V1.json and .xml. A client reads it to tell a known annotation from a stray one.

Its terms come from three sources:

Curated terms: the terms listed below, each with its type and where it applies.
Reserved terms: instance annotations that responses carry, and set-level terms.
The term rule: each DataSource and field attribute becomes a term, named by upper-casing its first letter. A field's hint is AsterData.Hint, and a DataSource's pluralTitle is AsterData.PluralTitle. An attribute the rule cannot carry goes in AsterData.Attributes, as one object.

Where a term applies is one of: an entity type (EntityType), a complex type, a function, a property (Property), a navigation property, an entity set, an entity container, a type definition, or an annotation. The table gives the type in the vocabulary's own names.

Field terms

Applied to a property.

Term	Type	Meaning
`Type`	`Edm.String`	The field type name, where the Edm type does not determine it.
`ForeignKey`	`Edm.String`	The `foreignKey` as written in the DataSource.
`Required`	`Edm.Boolean`	The field is required. Key properties carry it explicitly.
`EmptyAsNull`	`Edm.Boolean`	Empty text is read as null before validation.
`Collation`	`Aster.Data.V1.CollationSpec`	The collation of a text property. Every text property publishes it, and a comparison, sort or `like` on the property uses it.
`SetOn`	`Edm.String`	The server sets the property on a write: `create` (on create only) or `update` (on every update). Used for audit fields. Such a field is also `Core.Computed`.
`RootValue`	`Edm.Untyped`	On a tree's parent property, the value that marks a root. The default is null.
`MinLength`	`Edm.Int64`	The smallest length of a string value. Used by the `lengthRange` validator.
`MaxLength`	`Edm.Int64`	The largest length of a string value. Used by the validator. It is not the storage length.
`DisplayField`	`Edm.String`	The field of the related DataSource shown in place of this foreign key. Also on navigation properties.
`ValueMap`	`Edm.Untyped`	The `valueMap` exactly as written.
`ValueMapRef`	`Edm.Untyped`	The `valueMap`, with its labels as message references.
`TitleRef`	`Edm.Untyped`	The title as a message reference, resolved per language. Also on entity types.
`PromptRef`	`Edm.Untyped`	The prompt as a message reference, resolved per language.
`ErrorMessage`	`Edm.String`	Applied to a validation annotation, not to the property itself: the message shown when that validation term fails.
`Formula`	`Edm.Untyped`	The formula of a computed field, as written.
`Template`	`Edm.Untyped`	The template of a computed field, as written.
`Validators`	`Edm.Untyped` collection	The `validators` list exactly as written.
`Mask`	`Edm.Untyped`	The `mask` validator, without its type.
`MatchesField`	`Edm.Untyped`	The `matchesField` validator, without its type.
`IsUnique`	`Edm.Untyped`	The `isUnique` validator, without its type.
`DefaultValue`	`Edm.Untyped`	The value a new record starts with.
`RequiredMessage`	`Edm.Untyped`	The message shown when a required value is missing.
`ValidateOnChange`	`Edm.Untyped`	Validate the field when its value changes.
`EditorType`	`Edm.Untyped`	The form editor for the field.
`SummaryFunction`	`Edm.Untyped`	The default summary function for grid summaries.
`CanGroupBy`	`Edm.Boolean`	The field may be grouped by.
`Hint`	`Edm.Untyped`	Hint text for the field.
`Format`	`Edm.Untyped`	The display format of the field.
`Width`, `MinWidth`	`Edm.Untyped`	The default and the smallest column width.

Entity type and DataSource terms

Term	Type	Applies to	Meaning
`PluralTitle`	`Edm.String`	Entity type, complex type, function	The plural form of the title.
`TitleField`	`Edm.String`	Entity type, complex type, function	The field that names a record.
`Attributes`	`Edm.Untyped`	Entity type, complex type, function, property	Attributes the term rule cannot carry, as one object.

Term	Type	Applies to	Meaning
`Owned`	`Edm.Boolean`	Navigation property	The target entities belong to the source entity. They are written with it and deleted with it.
`CascadeDelete`	`Edm.Boolean`	Navigation property	On the to-many navigation of a hierarchy's children. Deleting a node deletes the nodes below it, in one atomic group. Preview with `AsterData.DeletePreview()`.
`AtomicGroup`	`Edm.String`	Entity set	The set's atomic group label in this service, such as `g1`. Writes to sets with the same label may go in one changeset. A set without the term cannot share a changeset with any other write.
`UpdatesWithoutRead`	`Edm.Boolean`	Entity set	An update of a row the caller may write but not read is accepted with `If-Match: *`. The response shows the fields as null.
`DeletesWithoutRead`	`Edm.Boolean`	Entity set	A delete of a row the caller may delete but not read is accepted with `If-Match: *`.
`StoredType`	`Edm.String`	Type definition	On an encoded property, the type the value is stored and compared as: `Int64` or `UInt128`.
`Encoding`	`Edm.String`	Type definition	On an encoded property, how the stored value is written: `decimal`, `padded:N`, or `globalId:Tag`.

Instance annotations

These appear on responses. They have no AppliesTo.

Annotation	Type	Appears on	Meaning
`InvalidateCache`	`Edm.Boolean`	A write response	The client should drop what it holds of the set. Sent by a set-based write and by a FileSource operation.
`AffectedRows`	`Edm.Int64`	A set-based write response	The number of rows the write changed or removed. Answers 200 where a single write would answer 204.
`Hidden`	`Edm.String` collection	An entity	The names of fields hidden for this record and caller. They are null in the entity, which means unknown, not empty.
`SuggestedValue`	`Edm.Untyped`	An error detail	The value the validator suggests in place of the one refused.
`StopOnError`	`Edm.Boolean`	An error detail	The validator asks that validation of the property stop at this failure. The server still reports every failure.

Container terms

Term	Type	Meaning
`Preferences`	`Aster.Data.V1.PreferenceSpec` collection	The `Prefer` tokens of the AsterData extensions the service understands, with the values each takes. See OData support.
`RequestContext`	`Aster.Data.V1.ContextSpec` collection	The request-context values the service declares. A client sends them in the `Aster-Context` header or the `aster-context` query parameter.
`UserSource`	`Edm.String`	The entity set with one row per signed-in user.

Functions

Filter functions

These run in $filter. Call them with the AsterData. prefix, as in AsterData.icontains(Name,'ann'). The full name Aster.Data.V1.icontains also works.

Function	Parameters	Returns	Meaning
`icontains(Property, Value)`	property, string	`Edm.Boolean`	The property contains the value under its catalog collation. Null on a null operand.
`istartswith(Property, Value)`	property, string	`Edm.Boolean`	The property starts with the value under its catalog collation.
`iendswith(Property, Value)`	property, string	`Edm.Boolean`	The property ends with the value under its catalog collation.
`like(Property, Pattern)`	property, string	`Edm.Boolean`	SQL `LIKE` by code point: `%` matches any run, `_` one character, and a backslash escapes.
`ilike(Property, Pattern)`	property, string	`Edm.Boolean`	`LIKE` under the property's catalog collation.
`regexp(Property, Pattern, CaseInsensitive)`	property, string, optional boolean	`Edm.Boolean`	An unanchored PCRE search. `CaseInsensitive` defaults to false.

Aggregation methods

These run in $apply, in an aggregate clause, after with: aggregate(Name with AsterData.concat as Names).

Method	Meaning
`first`	The smallest value under the property's collation.
`concat`	The values as text in ascending order, joined by the property's `joinString` (`,` when it declares none). Each value is wrapped in its `joinPrefix` and `joinSuffix`.
`concatDistinct`	As `concat`, over the distinct values, in the order of their text.
`count`	The number of non-null values.

Bound operations

These are declared by the service on top of the model's own. Each is bound to the set or to an entity, and $metadata publishes them.

Operation	Kind	Bound to	Parameters	Meaning
`Validate`	Action	Entity set or entity	`Record`, `Mode` (`full` or `partial`, default `full`)	Runs the validators, server rules and gates over a record, as the save it stands for would: on the set a create, on an entity a replacement (`partial`: only what the record gives). Writes nothing. Answers 204 when it passes, and the save's 400 (or 403) when it does not.
`DeletePreview`	Function	Entity	none	Says what a `DELETE` of the entity would remove: the entity, its owned children at any depth, and its hierarchy descendants where a cascade is declared. Returns a `DeletePreviewSet` for each set touched, with the count and up to 1,000 keys (`Truncated` is true beyond that). Changes nothing. Answers 403 if the delete would reach a row the caller cannot see. A set that refuses deletes is listed in `Refused` with its reason.
`DeletePreviewSet`	Complex type	Not bound	none	One entry of the `DeletePreview` result: the set, the count, the keys and `Truncated`.
`changeKey`	Action	Entity	`NewKey`	Changes the key of the entity and returns it. Offered only where the key is neither server-assigned nor immutable and the set accepts updates.

File operations

Sets that store files (FileSource sets) have these operations. They are bound to the collection. File is a record of the set, with the set's own property names, and Version is an Edm.DateTimeOffset.

Operation	Kind	Parameters	Meaning
`saveFile`	Action	`File`	Saves a new file, or a new version of one, and returns the entity.
`renameFile`	Action	`File`, `NewName`, optional `NewType`, `NewFormat`	Renames a file and returns the entity. `NewType` and `NewFormat` are offered where the set has a file type or format field, and change them with the name.
`removeFile`	Action	`File`	Removes a file.
`removeFileVersion`	Action	`File`, `Version`	Removes one version of a file.
`listFiles`	Function	none	The files of a versioned set, one entry (the newest version) per file. Offered on versioned sets only.
`listFileVersions`	Function	`File`	The versions of one file.
`getFileVersion`	Function	`File`, `Version`	One version of a file, as an entity.
`hasFileVersion`	Function	`File`, `Version`	Whether a file has the version, as an `Edm.Boolean`.