logo
logo

Domain specifications

A domain is a library of specifications and mappings, such as parameters, responses, and data models used across multiple API definitions. A domain groups and versions related domain specifications and represents a specific business case. By default, OpenAPI works with the latest version of the domain specifications.

A domain consists of:

Domain properties

A domain in Sitecore Content Hub™ contains the following properties:

PropertyPurpose
NameName of the domain
DescriptionPurpose of the domain
EnabledState of the domain
DomainIdentifierIdentifier for the domain (required to fetch the OpenAPI documentation)
SpecificationCollection of versioned mappings

Domain specification

The domain specification represents the output specification that Content Hub requires for integrations. It includes:

PropertyDescription
entity_viewsCollection of distinct entity mappings
versionUnique integer version of specification
statusDomain status integer value:
  • Draft (int: 0) is default status
  • Active (int: 1) specification cannot be edited
  • Disabled (int: 2) cannot be retrieved via API

Note

For an example domain specification, see the Test a domain example, which uses the M.Asset entity definition.

EntityView

The EntityView represents a subset of entity members to retrieve on demand. It includes:

PropertyTypePurpose
identifierStringUnique identifier (has to be unique under the same domain).
entity_definition_nameStringName of the entity definition associated with a particular entity view.
related_pathsObjectDetermines if related paths should show.
public_linksBooleanDetermines if public links should show.
display_nameBooleanDetermines if the display name should show.
languagesArrayDetermines the cultures to include.
propertiesArrayDetermines the properties to include.
relationsList of RelationView elementsDetermines the relations to include.
system_propertiesSystemPropertiesView objectDetermines the system properties to include.
renditionsList of RenditionView objectsDetermines the renditions to include.

RelationView

The RelationView represents a subset of entity members to fetch based on relation definitions on demand. It includes:

PropertyPurpose
relation_nameThe name of the relation. Used to resolve the relation.
viewEntityView: the view for the related entities.
roleThe role for the relation. It is an integer (0: child, 1: parent).

SystemPropertiesView

The SystemPropertiesView represents a subset of system properties of the entity to extract. It includes:

PropertyTypePurpose
created_byBooleanDetermines if the username of the entity creator should show.
created_onDateTimeDetermines how the created on date and time should show.
idBooleanDetermines if the ID should show.
identifierBooleanDetermines if the identifier should show.
modified_byBooleanDetermines if the username of the entity modifier should show.
modified_onDateTimeDetermines how the modified on date and time should show.
versionBooleanDetermines whether the version of the entity should show.

RenditionView

The RenditionView represents a subset of renditions from the entity to extract. It includes:

PropertyPurpose
rendition_link_nameFor example: medium, thumbnail, metadata, or any custom rendition

ResourceView

The ResourceView represents the output of the OpenAPI call. The Content Hub API transforms the EntityView configuration into a ResourceView.

ResourceView includes:

PropertyPurpose
propertiesMember properties extracted from the entity
relationsRelations extracted from the entity
public_linksPublic links extracted from the entity
renditionsRenditions extracted from the entity
system_propertiesSystem properties extracted from the entity

OpenAPI class

The following class diagram shows the OpenAPI class.

Domain specification template

The following template is an example of a Content Hub OpenAPI 3.0 domain definition that illustrates the various types of domain components.

[
    {
        "version": ##DomainSpecificationVersionInteger##,
        "status": ##StatusInteger##,
        "entity_views": {
            "##ResourceViewId##": {
                "identifier": "##ResourceViewId##",
                "entity_definition_name": "##DefinitionName##",
                "public_links": true,
                "languages": [
                    "en-US"
                ],
                "properties": [
                    "##PropertyNameString##"
                ],
                "system_properties": {
                    "id": true,
                    "identifier": true,
                    "version": true,
                    "created_on": {
                        "language": "en-US",
                        "format": "dddd, MMMM dd, yyyy HH:mm:ss",
                        "utc_time_offset": "03:00"
                    },
                    "modified_on": {
                        "language": "en-US"
                    },
                    "created_by": true,
                    "modified_by": true
                },
                "relations": [
                    {
                        "relation_name": "##RelationName##",
                        "relation_role": 1,
                        "public_links": true,
                        "view": {
                            "identifier": "##AnyIdString##",
                            "entity_definition_name": "##RelatedEntityDefinitionName##",
                            "public_links": true,
                            "properties": [],
                            "relations": [],
                            "renditions": []
                        }
                    }
                ],
                "renditions": [
                    {
                        "rendition_link_name": "##RenditionType##"
                    }
                ]
            }
        }
    }
]

Can we improve this article ? Provide feedback