Interface Documentation

Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Consumer Requirements

Consumers MUST ignore unknown properties / structures of the document. This allows the spec to be extended compatibly in the future.

Provider Requirements

An application / service that exposes or exports CSN Effective Interop:

MUST follow the described interface description. This SHOULD be validated via JSON Schema interface compliance and in the future SHOULD use of the API Metadata Validator, which supports validation beyond structural JSON Schema based constraints.

Schema Definitions

The root schema of the document is CSN Interop Root
The interface is available as JSON Schema: /spec-v1/csn-interop-effective.schema.json.

CSN Interop Root

Root of the CSN Interop Effective JSON document.

See Primer: Root Level Structure.

Property	Type	Description
$schema OPTIONAL	string	Link to JSON Schema for this CSN Interop Effective document. Adding this helps with automatic validation and code intelligence in some editors / IDEs. See https://tour.json-schema.org/content/06-Combining-Subschemas/02-id-and-schema JSON Schema Format: `uri-reference` Example Values: `"https://sap.github.io/csn-interop-specification/spec-v1/csn-interop-effective.schema.json"`
$id OPTIONAL	string	Optional URI for this document, that can acts as an ID. See https://tour.json-schema.org/content/06-Combining-Subschemas/02-id-and-schema JSON Schema Format: `uri-reference` Example Values: `"https://sap.github.io/csn-interop-specification/spec-v1/csn-interop-effective.ext.schema.json"` `"https://sap.github.io/csn-interop-specification/spec-v1/csn-interop-effective.schema.json"`
csnInteropEffective MANDATORY	string	Existence of this property indicated that the file is a CSN Interop Effective document. The value states the specification version it has been created against. Allowed Values: `"1.0"`
$version MANDATORY	string	The version of the CDS CSN. For this version of CSN Interop it is fixed to `2.0`. This MUST be provided to ensure that CSN Interop is a valid subset of CDS CSN in general. Allowed Values: `"2.0"`
meta OPTIONAL	Meta	Meta information that apply to the CSN document as a whole.
definitions MANDATORY	Definitions	Dictionary of CSN modeling artifacts.
i18n OPTIONAL	i18n	Dictionary of translated texts.
Additional Properties `^__.+$` OPTIONAL	string \| number \| boolean \| array \| object	Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^__.+$`

Property	Type	Description
creator OPTIONAL	string	Informal description of the creator of this CSN Document. Example Values: `"CDS Compiler v4.5.0"`
flavor OPTIONAL	string	Informal hint which CSN flavor is used. The values are currently NOT standardized. A CSN flavor can be understood as an alias to particular feature set of CSN overall. In CSN Interop we leave some features open and to be defined in the document itself, this is why we don't have a fixed flavor. Example Values: `"effective"` `"inferred"`
document OPTIONAL	Document (Metadata)	Meta information about the document content.
features OPTIONAL	Features (Metadata)	Feature dimensions that this CSN document fulfills.
Additional Properties `^__.+$` OPTIONAL	string \| number \| boolean \| array \| object	Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^__.+$`

Document (Metadata)

Metadata that describes the document (and what it represents) itself.

Property	Type	Description
version OPTIONAL	string	The version of the CSN document / the described model itself (not the specification). We RECOMMEND to use the SemVer standard. Example Values: `"1.3.4"`
doc OPTIONAL	string	Human readable documentation that describes the overall CSN document. SHOULD be provided and rendered as CommonMark (Markdown).

Features (Metadata)

CSN feature-dimensions this document fulfills.

It is RECOMMENDED to explicitly state all feature dimensions of the document. Otherwise the consumer cannot rely on the information and may have to figure this out on his own.

Property	Type	Description
complete RECOMMENDED	boolean	Whether this document is complete and self-contained. It is RECOMMENDED to have complete CSN documents and set this to `true`. If true references to other CDS elements (e.g. `cds.Association`) MUST be resolvable within the same document.

Example Values

{
  "complete": true
}

Definitions

Each entry in the definitions dictionary is a definition of a named modeling artefact. The name is the absolute, fully qualified name of the definition, and the value is a record with the definition details.

Definition names MUST:

Not be an empty string.
Not start with @, __, ., ::.
Not end with . or ::.
Not contain the substring .. or :::.
Not contain the substring :: more than once.

See Primer: Definitions.

Property	Type	Description
Additional Properties `^(?![@]\|__\|.\|::).+$` OPTIONAL	DefinitionEntry	Additional properties MUST follow key name regexp pattern: `^(?![@]\|__\|.\|::).+$`

Example Values

{
  "SomeEntity": {
    "kind": "entity",
    "elements": {
      "SomeElement": {
        "@SomeProperty.upperCase": true,
        "type": "cds.String"
      }
    }
  }
}

DefinitionEntry

Definition of a CDS modeling artifact, put into Definitions.

One of the following: Context Definition | Entity Definition | Service Definition | Type Definition

Entity Definition

Entity definition refers to the structured description of an object or concept.

If it is exposed through a Service, it describes a data model. To expose it through a Service, the service name MUST be prefixed to the Entity name, separated by a . (dot). The actual data serialization format is defined by the Service protocol and chosen data format mapping.

If the entity is not exposed via a service, it only describes a conceptual domain object.

Property	Type	Description
kind MANDATORY	string	The modeling artefact is an entity. Constant Value: `entity`
elements MANDATORY	Element Definitions	Dictionary of the elements of the entity. The dictionary key is the element `name`, the value the element itself. MUST have at least one element.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Element Definitions

Dictionary of Element where the key is the name of the element and the value its definition.

The value can either be a standard CDS Type (cds.*) or a Custom Type.

Element names MUST:

Not be an empty string.
Not start with @, __, ::.
Not end with ::.
Not contain the substring . or :::.
Not contain the substring :: more than once.

Property	Type	Description
Additional Properties `^(?![@]\|__\|.\|::).+$` OPTIONAL	ElementEntry	Additional properties MUST follow key name regexp pattern: `^(?![@]\|__\|.\|::).+$`

ElementEntry

Definition of an Element, as put into Element Definitions.

An element can be either of a standard CDS Types or a Custom Type.

One of the following: Cds Type | Custom Type

Cds Type

The native CDS Type of an element, which will always start with cds..

Boolean Type

An element of type cds.Boolean.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Boolean` type. Constant Value: `cds.Boolean`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (Boolean)
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Boolean",
  "default": {
    "val": true
  }
}

String Type

An element of type cds.String.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.String` type. Constant Value: `cds.String`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
length OPTIONAL	number	Describes the maximum number of characters of the value. If not provided, unlimited length is assumed. Number Constraint: MUST have a minimum value of 1
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.String",
  "key": true,
  "length": 3,
  "default": {
    "val": "foo"
  }
}

LargeString Type

An element of type cds.LargeString.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.LargeString` type. Constant Value: `cds.LargeString`
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
length OPTIONAL	number	Describes the maximum number of characters of the value. If not provided, unlimited length is assumed. Number Constraint: MUST have a minimum value of 1
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.LargeString",
  "length": 3,
  "default": {
    "val": "large foo"
  },
  "notNull": true
}

Integer Type

An element of type cds.Integer.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Integer` type. Constant Value: `cds.Integer`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value integer
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Integer",
  "default": {
    "val": 123
  }
}

Integer64 Type

An element of type cds.Integer64.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Integer64` type. Constant Value: `cds.Integer64`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value integer
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Integer64",
  "default": {
    "val": 123
  }
}

Decimal Type

An element of type cds.Decimal.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Decimal` type. Constant Value: `cds.Decimal`
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value number
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
precision OPTIONAL	number	Total number of digits in a number. This includes both the digits before and after the decimal point. The semantics of the choices follows the OData v4 Precision specification. Default Value: `34` Number Constraint: MUST have a minimum value of 1
scale OPTIONAL	Decimal Scale (Number) \| Decimal Scale (Type)	Describes the number of digits to the right of the decimal point in a number. Default Value: `floating` One of: Decimal Scale (Number) Decimal Scale (Type)
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Decimal",
  "precision": 16,
  "scale": 3,
  "default": {
    "val": 12.3
  }
}

Double Type

An element of type cds.Double.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Double` type. Constant Value: `cds.Double`
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value number
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Double",
  "default": {
    "val": 123
  }
}

Date Type

An element of type cds.Date.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Date` type. Constant Value: `cds.Date`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Date",
  "key": true
}

Time Type

An element of type cds.Time.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Time` type. Constant Value: `cds.Time`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Time",
  "key": true
}

DateTime Type

An element of type cds.DateTime.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.DateTime` type. Constant Value: `cds.DateTime`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.DateTime",
  "key": true
}

Timestamp Type

An element of type cds.Timestamp.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Timestamp` type. Constant Value: `cds.Timestamp`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Timestamp",
  "key": true
}

UUID Type

An element of type cds.UUID.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.UUID` type. Constant Value: `cds.UUID`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.UUID",
  "key": true
}

Association Type

An element of type cds.Association, to express a "reference" relation across Entities. It works the same way as a cds.Composition, with the difference that the latter assumes a composite relationship.

See Primer: Associations.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Association` type. Constant Value: `cds.Association`
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
target MANDATORY	string	The (fully qualified) target entity name. Association Target: Entity Definition
cardinality MANDATORY	Cardinality Object	The cardinality indicates the number of instances of one entity that can or must be associated with each instance of another entity. SHOULD provide `min` and `max` values explicitly.
on MANDATORY	Array<Structured Element Reference \| Equals Operator \| AND Operator \| On Value>	The property `on` holds a sequence of operators and operands to describe the join condition. One building block of the sequence consists of the following in the given order: - Reference to a field of the association or composition target - Equals Operator "=" - One of the following: - Reference to a field of the source entity - Constant Value This building block states that the value of the first entry of the array using "ref" should equal the value of the third entry of the array. In addition, several building blocks can be lined up using an "and" operator More information can be found here: * https://cap.cloud.sap/docs/cds/csn#assoc-on Example Values: `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]}]` `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]},"and",{"ref":["to_Connection","ConnectionID"]},"=",{"ref":["ConnectionID"]}]` `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]},"and",{"ref":["to_Connection","ConnectionID"]},"=",{"val":"1234567"}]`
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Association",
  "target": "Airport",
  "cardinality": {
    "max": "*"
  },
  "on": [
    {
      "ref": [
        "to_DepartureAirport",
        "AirportID"
      ]
    },
    "=",
    {
      "ref": [
        "DepartureAirport_AirportID"
      ]
    }
  ]
}

Composition Type

An element of type cds.Composition, to express a "contains" relation across Entities. It works the same as a cds.Association.

See Primer: Associations.

Property	Type	Description
type MANDATORY	string	The modeling artefact is a `cds.Composition` type. Constant Value: `cds.Composition`
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
target MANDATORY	string	The (fully qualified) target entity name. Association Target: Entity Definition
cardinality MANDATORY	Cardinality Object	The cardinality indicates the number of instances of one entity that can or must be associated with each instance of another entity. SHOULD provide `min` and `max` values explicitly.
on MANDATORY	Array<Structured Element Reference \| Equals Operator \| AND Operator \| On Value>	The property `on` holds a sequence of operators and operands to describe the join condition. One building block of the sequence consists of the following in the given order: - Reference to a field of the association or composition target - Equals Operator "=" - One of the following: - Reference to a field of the source entity - Constant Value This building block states that the value of the first entry of the array using "ref" should equal the value of the third entry of the array. In addition, several building blocks can be lined up using an "and" operator More information can be found here: * https://cap.cloud.sap/docs/cds/csn#assoc-on Example Values: `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]}]` `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]},"and",{"ref":["to_Connection","ConnectionID"]},"=",{"ref":["ConnectionID"]}]` `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]},"and",{"ref":["to_Connection","ConnectionID"]},"=",{"val":"1234567"}]`
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Composition",
  "target": "Airport",
  "cardinality": {
    "max": "*"
  },
  "on": [
    {
      "ref": [
        "to_DepartureAirport",
        "AirportID"
      ]
    },
    "=",
    {
      "ref": [
        "DepartureAirport_AirportID"
      ]
    }
  ]
}

Custom Type

An Element can be of a Custom Type (aka Derived Type) instead of a standard CDS type. This allows several Elements to share / reuse the same Custom Type definition. This MAY also imply shared semantics.

The Custom Type has a custom type value, which is the name of the Type Definition describing the shared type. This type value MUST NOT start with cds., to avoid conflicts with core CDS data types.

The Type Definition that the Custom Type points to MUST be described in the same CSN document in the definitions section with "kind": "type". The Element MUST NOT add properties that are not supported by the Custom Types base CDS type.

CSN Interop Effective adds further constraints to make a simple type lookup possible:

A Custom Type MUST NOT point to another Custom Type (no recursion).
The properties and annotations of the Custom Type MUST be merged into the Element it is used, to fulfill the "effective" quality.

This will allow a consumer to do a simple dictionary lookup to find the CDS Type of a Custom Type. All other properties describing the Custom Type can already be found at the Custom Type itself.

🚧 TODO: Clarify if Custom Type can also be cds.Association or cds.Composition. If yes, add target, on and cardinality here.

Property	Type	Description
type MANDATORY	string	Use of a custom type. MUST not start with `cds.`. Regex Pattern: `^(?!cds.).*$`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (Custom Type)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
length OPTIONAL	number	Describes the maximum number of characters of the value. If not provided, unlimited length is assumed. Number Constraint: MUST have a minimum value of 1
scale OPTIONAL	Decimal Scale (Number) \| Decimal Scale (Type)	Describes the number of digits to the right of the decimal point in a number. Default Value: `floating` One of: Decimal Scale (Number) Decimal Scale (Type)
precision OPTIONAL	number	Total number of digits in a number. This includes both the digits before and after the decimal point. The semantics of the choices follows the OData v4 Precision specification. Default Value: `34` Number Constraint: MUST have a minimum value of 1
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "CONTROLLING_AREA",
  "key": true
}

Default Value (Custom Type)

Property	Type	Description
val MANDATORY	string,number,boolean,object,null	Default Value for a Custom Type. The chosen value type MUST match the CDS Type that the custom type chose.

Default Value (Boolean)

Property	Type	Description
val MANDATORY	boolean,null	Default Value for Boolean Type.

Default Value (String)

Property	Type	Description
val MANDATORY	string,null	Default Value for String Types.

Default Value integer

Property	Type	Description
val MANDATORY	integer,null	Default Value for Integer Type.

Default Value number

Property	Type	Description
val MANDATORY	number,null	Default Value for DecimalScaleNumber: Type.

Default Value object

Indicates the default value.

Property	Type	Description
val MANDATORY	object,null	Default Value for (structured) Object Types.

Value Object

Enum CQN literal value expression.

The literal expression optionally specifies a constant val as a literal plus optional annotations.

Property	Type	Description
val OPTIONAL	string,number,boolean,null	Value of the enum.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Decimal Scale (Number)

Total number of digits that are present after the decimal point in a number. The scale can hold from zero up to the total numeric precision

Type: number
Number Constraint: MUST have a minimum value of 0

Decimal Scale (Type)

The cds.Decimal type can also set scale to a fixed type.

The semantics of the choices follows the OData v4 Scale specification.

Type: string
Default Value: floating
Allowed Values:

"floating": The value floating means that the decimal property represents a decimal floating-point number whose number of significant digits is the value of the Precision

See https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html#sec_Scale

Cardinality Object

The cardinality indicates the number of instances of one entity that can or must be associated with each instance of another entity.

SHOULD provide min and max values explicitly.

Property	Type	Description
src OPTIONAL	number	Describes if a source entity always exist. If `src` is not set then unknown is assumed.
min RECOMMENDED	number	Specifies the targets minimum cardinality. Default Value: `0`
max RECOMMENDED	number,string	Specifies the targets maximum cardinality. MUST be one of: * positive Integer (1,2,...) * `` as String Default Value*: `1`

Example Values

{
  "max": "*"
}

{
  "min": 1,
  "max": "*"
}

Structured Element Reference

Describes the target or source of the association.

Property	Type	Description
ref MANDATORY	Array<string>	Description of the target with association name and target element name in target entity` Description of the source source element name MUST NOT: * use $ as leading character of an element * use session variables Array Item Association Target: Cds Type

Equals Operator

The operator "="

Type: string
Constant Value: =

AND Operator

The operator "and"

Type: string
Constant Value: and

On Value

Value for an on condition

Property	Type	Description
val MANDATORY	string,number	Value for the on condition.

Enum Dictionary

Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.

Property	Type	Description
Additional Properties `^.+$` OPTIONAL	Value Object	Additional properties MUST follow key name regexp pattern: `^.+$`

Example Values

{
  "submitted": {
    "val": 1
  },
  "fulfilled": {
    "val": 2
  }
}

{
  "male": {},
  "female": {},
  "non_binary": {
    "val": "non-binary"
  }
}

Element Reference

Element reference denotes a reference to an element.

It is RECOMMENDED to use the ElementReferenceObject notation.

See Primer: Literals for Enum and ElementRef values.

One of:

Element Reference String
Element Reference Object

Element Reference String

Element reference denotes a reference to an element, i.e. a member of the elements object of an entity in the following format:

"<definition name>": {
  "<annotation key of type ElementReference>": "<element name>"

Type: string

Element Reference Object

Element reference denotes a reference to an element, i.e. a member fo the elements object of an entity in the following format:

"<definition name>": {
  "<annotation key of type ElementReference>": {"=": "<element name>"}

Property	Type	Description
= MANDATORY	string	This is the references elements name. Association Target: Cds Type

Enum Value Object

Enum values are given in object format:

"<definition name>": {
  "<annotation key of type Enum>": {"#": "<enum value>"}

Property	Type	Description
# MANDATORY	string	The enum value as a string.

Type Definition

In CSN it is possible to define Custom Types. They can be referred to in Element type, making them "reusable" / "shared" types.

In CSN Interop Effective, the "effective" quality brings additional requirements:

The derived types MUST always have a cds.* type and MUST NOT point to other derived types. This ensures that consumers do not have to support recursive type lookups.
Attributes and annotations MUST be also copied and merged with those defined in the element using this derived type. This ensures that consumers only have to lookup the CDS type and don't have to merge attributes and annotations.

Boolean Type Definition

A type definition of type cds.Boolean.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Boolean` type. Constant Value: `cds.Boolean`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (Boolean)
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Boolean",
  "kind": "type",
  "default": {
    "val": true
  }
}

String Type Definition

A type definition of type cds.String.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.String` type. Constant Value: `cds.String`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
length OPTIONAL	number	Describes the maximum number of characters of the value. If not provided, unlimited length is assumed. Number Constraint: MUST have a minimum value of 1
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.String",
  "kind": "type",
  "key": true,
  "length": 3,
  "default": {
    "val": "foo"
  }
}

LargeString Type Definition

A type definition of type cds.LargeString.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.LargeString` type. Constant Value: `cds.LargeString`
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
length OPTIONAL	number	Describes the maximum number of characters of the value. If not provided, unlimited length is assumed. Number Constraint: MUST have a minimum value of 1
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Integer Type Definition

A type definition of type cds.Integer.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Integer` type. Constant Value: `cds.Integer`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value integer
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Integer",
  "kind": "type",
  "default": {
    "val": 123
  }
}

Integer64 Type Definition

A type definition of type cds.Integer64.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Integer64` type. Constant Value: `cds.Integer64`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value integer
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Decimal Type Definition

A type definition of type cds.Decimal.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Decimal` type. Constant Value: `cds.Decimal`
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value number
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
precision OPTIONAL	number	Total number of digits in a number. This includes both the digits before and after the decimal point. The semantics of the choices follows the OData v4 Precision specification. Default Value: `34` Number Constraint: MUST have a minimum value of 1
scale OPTIONAL	Decimal Scale (Number) \| Decimal Scale (Type)	Describes the number of digits to the right of the decimal point in a number. Default Value: `floating` One of: Decimal Scale (Number) Decimal Scale (Type)
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Decimal",
  "kind": "type",
  "precision": 16,
  "scale": 3,
  "default": {
    "val": 12.3
  }
}

Double Type Definition

A type definition of type cds.Double.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Double` type. Constant Value: `cds.Double`
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value number
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Date Type Definition

A type definition of type cds.Date.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Date` type. Constant Value: `cds.Date`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Date",
  "kind": "type",
  "key": true
}

Time Type Definition

A type definition of type cds.Time.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Time` type. Constant Value: `cds.Time`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

DateTime Type Definition

A type definition of type cds.DateTime.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.DateTime` type. Constant Value: `cds.DateTime`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Timestamp Type Definition

A type definition of type cds.Timestamp.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Timestamp` type. Constant Value: `cds.Timestamp`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
enum OPTIONAL	Enum Dictionary	Dictionary of enum member elements with the name being the enum symbol and the value being a CQN literal value expression.
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

UUID Type Definition

A type definition of type cds.UUID.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.UUID` type. Constant Value: `cds.UUID`
key OPTIONAL	boolean	Indicates that this element is used as a primary key. Multiple primary keys MAY be used in case of a composite ID.
notNull OPTIONAL	boolean	Indicates that this element does not accept NULL values, which means that you cannot insert or update a record without adding a value to this field.
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
default OPTIONAL	Default Value (String)
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Association Type Definition

A type definition of type cds.Association.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Association` type. Constant Value: `cds.Association`
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
target MANDATORY	string	The (fully qualified) target entity name. Association Target: Entity Definition
cardinality MANDATORY	Cardinality Object	The cardinality indicates the number of instances of one entity that can or must be associated with each instance of another entity. SHOULD provide `min` and `max` values explicitly.
on MANDATORY	Array<Structured Element Reference \| Equals Operator \| AND Operator \| On Value>	The property `on` holds a sequence of operators and operands to describe the join condition. One building block of the sequence consists of the following in the given order: - Reference to a field of the association or composition target - Equals Operator "=" - One of the following: - Reference to a field of the source entity - Constant Value This building block states that the value of the first entry of the array using "ref" should equal the value of the third entry of the array. In addition, several building blocks can be lined up using an "and" operator More information can be found here: * https://cap.cloud.sap/docs/cds/csn#assoc-on Example Values: `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]}]` `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]},"and",{"ref":["to_Connection","ConnectionID"]},"=",{"ref":["ConnectionID"]}]` `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]},"and",{"ref":["to_Connection","ConnectionID"]},"=",{"val":"1234567"}]`
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Association",
  "kind": "type",
  "target": "Airport",
  "cardinality": {
    "max": "*"
  },
  "on": [
    {
      "ref": [
        "to_DepartureAirport",
        "AirportID"
      ]
    },
    "=",
    {
      "ref": [
        "DepartureAirport_AirportID"
      ]
    }
  ]
}

Composition Type Definition

A type definition of type cds.Composition.

Property	Type	Description
kind MANDATORY	string	The kind property is used when defining derived types. In this case Kind = "type". Constant Value: `type`
type MANDATORY	string	The modeling artefact is a `cds.Composition` type. Constant Value: `cds.Composition`
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
target MANDATORY	string	The (fully qualified) target entity name. Association Target: Entity Definition
cardinality MANDATORY	Cardinality Object	The cardinality indicates the number of instances of one entity that can or must be associated with each instance of another entity. SHOULD provide `min` and `max` values explicitly.
on MANDATORY	Array<Structured Element Reference \| Equals Operator \| AND Operator \| On Value>	The property `on` holds a sequence of operators and operands to describe the join condition. One building block of the sequence consists of the following in the given order: - Reference to a field of the association or composition target - Equals Operator "=" - One of the following: - Reference to a field of the source entity - Constant Value This building block states that the value of the first entry of the array using "ref" should equal the value of the third entry of the array. In addition, several building blocks can be lined up using an "and" operator More information can be found here: * https://cap.cloud.sap/docs/cds/csn#assoc-on Example Values: `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]}]` `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]},"and",{"ref":["to_Connection","ConnectionID"]},"=",{"ref":["ConnectionID"]}]` `[{"ref":["to_Connection","AirlineID"]},"=",{"ref":["AirlineID"]},"and",{"ref":["to_Connection","ConnectionID"]},"=",{"val":"1234567"}]`
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Example Values

{
  "type": "cds.Composition",
  "kind": "type",
  "target": "Airport",
  "cardinality": {
    "max": "*"
  },
  "on": [
    {
      "ref": [
        "to_DepartureAirport",
        "AirportID"
      ]
    },
    "=",
    {
      "ref": [
        "DepartureAirport_AirportID"
      ]
    }
  ]
}

Service Definition

A CDS Service indicates that Entities are exposed to outside consumers via an API.

To assign Entities to a Service, the entity name MUST be prefixed with the service name, separated by a .. Please be aware that this will also change the target values of cds.Association and cds.Composition. For an example, see airline-service.json.

A consumer MAY decide to shorten the names by only considering the Entities assigned to a particular Service and then removing the Service prefixes again.

To indicate which assigned Entities are root in a composition hierarchy, use the @ObjectModel.compositionRoot annotation.

See Primer: Service Definitions.

Property	Type	Description
kind MANDATORY	string	The modeling artefact is a service. Constant Value: `service`
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

Context Definition

A context corresponds to a CAP CSN Namespace. It is used to create a bounded context that bundles elements of different kinds together. The context will become part of the entity / element name.

The context is also useful to avoid local or global name collisions.

See Primer: Context.

Property	Type	Description
kind MANDATORY	string	The modeling artefact is a context. Constant Value: `context`
doc OPTIONAL	string	Human readable documentation. SHOULD be provided and rendered as CommonMark (Markdown).
Additional Properties `^(@\|__).+$` OPTIONAL	string \| number \| boolean \| array \| object	Annotations or private properties MAY be added. Annotations MUST start with `@`. In CSN Interop Effective the annotations MUST follow the "flattened" form: Every record / object in an annotation will be flattened into a `.` (dot). Exception: Once there is an array, the flattening is stopped and the values inside the array are preserved as they are ("structured"). Correct annotations examples: * `"@Common.bar": "foo"` * `"@Common.foo.bar": true` * `"@Common.array": [{ "foo": true }]` Or Private properties, starting with `__`. MAY be ignored by the consumers, as they have no cross-aligned, standardized semantics. Additional properties MUST follow key name regexp pattern: `^(@\|__).+$`

i18n

i18n contains translated texts for one or more languages. They are usually used in annotations like @EnduserText.

Key is the language key, value is a dictionary of language text translations.

The language key MUST follow the standard of RFC 1766 (or IETF's BCP 47).

See Primer: Language-dependent annotation values.

Property	Type	Description
Additional Properties `^[a-zA-Z]{2,8}(-[a-zA-Z0-9]{1,8}){0,2}$` OPTIONAL	Language texts	Additional properties MUST follow key name regexp pattern: `^[a-zA-Z]{2,8}(-[a-zA-Z0-9]{1,8}){0,2}$`

Example Values

{
  "de": {
    "I_COSTCENTER@ENDUSERTEXT.LABEL": "Kostenstelle",
    "I_COSTCENTER.CONTROLLINGAREA@ENDUSERTEXT.LABEL": "Kostenrechnungskreis"
  }
}

Language texts

Language Text contains translations for one specific languages.

Key is the i18n key, value is the translation of the term.

An i18n pointer is a string that starts with {i18n> and ends with }. In between is the key.

Example: To link to the i18n key I_COSTCENTER@ENDUSERTEXT.LABEL, the i18n pointer is {i18n>I_COSTCENTER@ENDUSERTEXT.LABEL}.

The i18n pointers within the document MUST be fully self contained:

An i18n resolved pointer MUST be used (referred to) within this CSN document at least once.
All i18n pointers in this CSN document MUST have a corresponding i18n dictionary entry.

Property	Type	Description
Additional Properties `^.+$` OPTIONAL	string	Translation of the term. Additional properties MUST follow key name regexp pattern: `^.+$`

Example Values

{
  "I_COSTCENTER@ENDUSERTEXT.LABEL": "Kostenstelle",
  "I_COSTCENTER.CONTROLLINGAREA@ENDUSERTEXT.LABEL": "Kostenrechnungskreis"
}

Notational Conventions​

Consumer Requirements​

Provider Requirements​

Schema Definitions​

CSN Interop Root​

Meta​

Example Values​

Document (Metadata)​

Features (Metadata)​

Example Values​

Definitions​

Example Values​

DefinitionEntry​

Entity Definition​

Element Definitions​

ElementEntry​

Cds Type​

Boolean Type​

Example Values​

String Type​

Example Values​

LargeString Type​

Example Values​

Integer Type​

Example Values​

Integer64 Type​

Example Values​

Decimal Type​

Example Values​

Double Type​

Example Values​

Date Type​

Example Values​

Time Type​

Example Values​

DateTime Type​

Example Values​

Timestamp Type​

Example Values​

UUID Type​

Example Values​

Association Type​

Example Values​

Composition Type​

Example Values​

Custom Type​

Example Values​

Default Value (Custom Type)​

Default Value (Boolean)​

Default Value (String)​

Default Value integer​

Default Value number​

Default Value object​

Value Object​

Decimal Scale (Number)​

Decimal Scale (Type)​

Cardinality Object​

Example Values​

Structured Element Reference​

Equals Operator​

AND Operator​

On Value​

Enum Dictionary​

Example Values​

Element Reference​

Element Reference String​

Element Reference Object​

Enum Value Object​

Type Definition​

Boolean Type Definition​

Example Values​

String Type Definition​

Example Values​

LargeString Type Definition​

Integer Type Definition​

Example Values​

Integer64 Type Definition​

Decimal Type Definition​

Example Values​

Double Type Definition​

Notational Conventions

Consumer Requirements

Provider Requirements

Schema Definitions

CSN Interop Root

Meta

Example Values

Document (Metadata)

Features (Metadata)

Example Values

Definitions

Example Values

DefinitionEntry

Entity Definition

Element Definitions

ElementEntry

Cds Type

Boolean Type

Example Values

String Type

Example Values

LargeString Type

Example Values

Integer Type

Example Values

Integer64 Type

Example Values

Decimal Type

Example Values

Double Type

Example Values

Date Type

Example Values

Time Type

Example Values

DateTime Type

Example Values

Timestamp Type

Example Values

UUID Type

Example Values

Association Type

Example Values

Composition Type

Example Values

Custom Type

Example Values

Default Value (Custom Type)

Default Value (Boolean)

Default Value (String)

Default Value integer

Default Value number

Default Value object

Value Object

Decimal Scale (Number)

Decimal Scale (Type)

Cardinality Object

Example Values

Structured Element Reference

Equals Operator

AND Operator

On Value

Enum Dictionary

Example Values

Element Reference

Element Reference String

Element Reference Object

Enum Value Object

Type Definition

Boolean Type Definition

Example Values

String Type Definition

Example Values

LargeString Type Definition

Integer Type Definition

Example Values

Integer64 Type Definition

Decimal Type Definition

Example Values

Double Type Definition