GraphQL Mapping

This page describes how CK language 2 elements appear in a tenant's GraphQL schema (asset repository): attribute access, CK interfaces as GraphQL interfaces, and the CK meta API.

Element Names

GraphQL names of CK elements are the model name and the element name without separators. An element version above 1 is appended without the dash; version 1 has no suffix:

CK element	GraphQL name
Acme.Assets/Named-1	AcmeAssetsNamed
Acme.Assets/Named-2	AcmeAssetsNamed2

The rule applies to all element kinds, so successive interface versions coexist in one schema. Interfaces derived from abstract CK types keep their existing <Type>Interface names.

Name collisions

The compiler only rejects an interface with exactly the name of a type of the same model (message 93). Other collisions of generated GraphQL names are not detected yet and make the tenant's GraphQL schema fail to build — for example an element literally named Named2 next to Named-2, or an interface whose name equals a generated name such as <Type>Interface, <Type>Input or <Type>Update. Avoid such names.

Attribute access

The access of an attribute assignment shapes the generated schema and the generic CRUD path:

access	Output field	Input / …InputUpdate field	Filter / sort	Generic create / update
ReadWrite	yes	yes	yes	allowed
ReadOnly	yes	yes	yes	allowed — not enforced in this phase
MethodOnly	yes	no	yes	rejected (ATTRIBUTE_NOT_WRITABLE)
Hidden	no	no	rejected (ATTRIBUTE_NOT_QUERYABLE)	rejected (ATTRIBUTE_NOT_WRITABLE)

ReadOnly is parsed, persisted and reported by the CK meta API (access), but the generic input types and mutations treat it like ReadWrite for now.

The complete list of paths Hidden covers — and the ones it does not cover yet — is in Access modifiers.

Errors

Access errors (ATTRIBUTE_NOT_WRITABLE, ATTRIBUTE_NOT_QUERYABLE) carry extensions.code, the attribute path and the operation. They never contain a value, in any environment; values inside entity-selector paths are redacted ([apiKeyHash=…]). Exception details (exception text, inner exceptions, stack traces in extensions.details) are returned only in the Development environment or with the opt-in setting GraphQl:ExposeExceptionDetails (OCTO_GraphQl__ExposeExceptionDetails); deployed services run as Production.

CK Interfaces as GraphQL Interfaces

Each CK interface of the tenant becomes a GraphQL interface type (named as above):

• Fields: the system fields of every runtime entity (rtId, ckTypeId, ...) plus one field per attribute member — its own and those of every interface it extends. Optional members are nullable.
• Implementing types: every entity type implementing the CK interface — directly, through a base type or through an extended interface — implements the GraphQL interface. If a type does not assign an optional member, it still gets the field; the field always resolves to null. If a type's fields cannot be aligned with the interface, the type is not linked to the GraphQL interface and the asset repository logs a warning.
• extends maps to GraphQL interface inheritance: the GraphQL interface implements all its (transitive) parent interfaces, and implementing object types list the full closure.
• Association members become interface fields only when every implementing type exposes the outbound association field of that role with the same shape (name, connection type, arguments). Otherwise the member is left out of the GraphQL interface and the asset repository logs a warning. Inbound association members are not exposed.
• Associations narrowed to an interface (targetCkInterfaceId): the navigation field's union only contains the concrete target types that implement the interface.

Select interface fields with a fragment:

query {
  runtime {
    acmeAssetsGateway(first: 10) {
      items {
        ... on AcmeAssetsIdentified {
          name
          description
          serialNumber
        }
      }
    }
  }
}

There is no query field that returns entities by interface yet (runtime.byInterface); query the concrete types and use fragments.

CK Meta API

The constructionKit query describes the CK language 2 meta model. The new enumeration-like values (visibility, derivable, access, kind, multiplicity) are strings with PascalCase names (Public, Model, Hidden, Instance, ...); value types (valueType, attributeValueType) are the existing GraphQL enum (STRING, RECORD, ...). Elements of CK language 1 models report the v1 defaults.

Type	New fields
CkType	visibility, derivable, declaredInterfaces, interfaces (declared, inherited and extended), methods (own and inherited)
CkTypeAttribute	access
CkRecord	visibility, derivable
CkEnum, CkAttribute, CkAssociationRole	visibility
CkModel	ckLanguage (1 when not declared), minEngineVersion, dependencyRanges { range floor } (null for exact-pinned models)
CkInterface (new)	ckInterfaceId, rtCkInterfaceId, description, visibility, deprecated, extends, allExtends, attributes (ckAttributeId, attributeName, attributeValueType, isOptional, including extended members), associations (ckAssociationRoleId, targetCkTypeId, targetCkInterfaceId, multiplicity, isOptional, declaringCkInterfaceId), methods, implementingTypes
CkMethod (new, definitions only)	methodId, qualifiedMethodId, declaringCkTypeId / declaringCkInterfaceId, kind, description, visibility, parameters (name, valueType, valueCkRecordId, valueCkEnumId, isOptional, sensitive, description), result, errors (CkMethodErrorDefinition), authorization (roles, allowSelf, scopes), execution (timeoutSeconds, idempotent)
ConstructionKitQuery	interfaces(ckModelIds, rtCkId, rtCkIds)

Internal elements are listed like public ones — internal means "not referencable from other models", not secret.

Example:

query {
  constructionKit {
    types(rtCkId: "Acme.Assets/Device") {
      items {
        visibility
        derivable
        interfaces { rtCkInterfaceId }
        methods {
          methodId
          kind
          parameters { name valueType isOptional sensitive }
          authorization { roles allowSelf }
        }
        attributes(first: 50) { items { attributeName access } }
      }
    }
    interfaces(ckModelIds: ["Acme.Assets"]) {
      items {
        rtCkInterfaceId
        extends { semanticVersionedFullName }
        attributes { attributeName isOptional }
        implementingTypes { semanticVersionedFullName }
      }
    }
    models(first: 50) {
      items {
        id { name }
        ckLanguage
        dependencyRanges { range floor }
      }
    }
  }
}

More CK meta queries: Construction Kit retrieval.

Methods

Method definitions are visible in the CK meta API only. They produce no mutation fields; method invocation arrives with the method runtime in a later phase.

See Also

• Access modifiers
• Interfaces