Entity Profile: HAL format

The HAL profile format describes the model of an entity type, its attributes and relations.

It also provides the search and create-form HAL-FORMS templates, which describe how to search and create new items of this type.

The entity profile uses standard link relation types and ContentGrid-specific extension link relation types. See the Link Relation Types reference for general information on link relation types and CURIEs.

The entity profile introduces the blueprint CURIE prefix (https://contentgrid.cloud/rels/blueprint/{rel}) for the following link relation types:

Link relation type Context Description
blueprint:attribute entity An attribute defined on the entity
blueprint:relation entity A relation defined on the entity
blueprint:attribute attribute An attribute that is nested inside an other attribute (nested object)
blueprint:constraint attribute A constraint on the attribute
blueprint:search-param attribute A search parameter for the attribute
blueprint:target-entity relation Points to the entity profile of the relation’s target entity type

Entity Profile Fields

The top-level entity profile resource contains:

Field Type Description
name string Internal entity name
title string Human-readable entity name (singular)
description string or null Description of the entity

The entity profile also contains embedded HAL resources:

  • blueprint:attribute: A list of the attributes that are present on the entity
  • blueprint:relation: A list of the relations that are present on the entity

The entity profile contains HAL links:

Link relation type name attribute Description
self N/A Links to this profile
describes collection Links to the entity collection URL
describes item URI template for linking to individual entity items
curies all See CURIEs
Entity profile overview
​
curl -i https://$APP_ID.$REGION.contentgrid.cloud/profile/invoices   \
    -H 'Accept: application/prs.hal-forms+json'   \
    -H "Authorization: Bearer $TOKEN"

GET /profile/invoices HTTP/1.1
Authorization: Bearer $TOKEN
Accept: application/prs.hal-forms+json

HTTP/1.1 200 OK
Content-Type: application/prs.hal-forms+json

{
  "name": "invoice",
  "title": "Invoice",
  "description": null,
  "_embedded": {
    "blueprint:attribute": [...],
    "blueprint:relation": [...]
  },
  "_links": {
    "self": {
      "href": "https://app.contentgrid.example/profile/invoices",
      "title": "Invoice"
    },
    "describes": [
      {
        "href": "https://app.contentgrid.example/invoices",
        "title": "Invoices",
        "profile": "https://app.contentgrid.example/profile/invoices",
        "name": "collection"
      },
      {
        "href": "https://app.contentgrid.example/invoices/{id}",
        "title": "Invoice",
        "name": "item",
        "templated": true
      }
    ],
    "curies": [
      {
        "href": "https://contentgrid.cloud/rels/contentgrid/{rel}",
        "name": "cg",
        "templated": true
      },
      {
        "href": "https://contentgrid.cloud/rels/blueprint/{rel}",
        "name": "blueprint",
        "templated": true
      }
    ]
  },
  "_templates": {
    "search": {...},
    "create-form": {...}
  }
}

Embedded Resources

The entity profile contains embedded resources that describe the entity’s attributes and relations.

Attribute (blueprint:attribute)

Entity attributes are embedded resources in the entity profile under the link relation blueprint:attribute.

Field Type Description
name string Attribute name
title string Human-readable title
type string Data type: string, long, double, boolean, date, datetime, object
description string or null Attribute description
readOnly boolean Whether the attribute is read-only
required boolean Whether the attribute is required

Each attribute itself contains embedded resources, describing details about the attribute:

Simple attribute 
{
  "name": "received",
  "title": "Received",
  "type": "date",
  "description": null,
  "readOnly": false,
  "required": true,
  "_embedded": {
    "blueprint:constraint": [
      {
        "type": "required"
      }
    ],
  }
}

Sub-attributes

Attributes with type: "object" (such as content attributes) can contain nested blueprint:attribute sub-attributes. Sub-attributes have the same structure as top-level attributes, recursively.

Content attribute with sub-attributes 
{
  "name": "document",
  "title": "Document",
  "type": "object",
  "description": null,
  "readOnly": false,
  "required": false,
  "_embedded": {
    "blueprint:attribute": [
      {
        "name": "filename",
        "title": "Filename",
        "type": "string",
        "description": null,
        "readOnly": false,
        "required": false
      },
      {
        "name": "mimetype",
        "title": "Mimetype",
        "type": "string",
        "description": "Technical indicator of the type of the file",
        "readOnly": false,
        "required": false
      },
      {
        "name": "length",
        "title": "Size",
        "type": "long",
        "description": "File size in bytes",
        "readOnly": true,
        "required": false
      }
    ]
  }
}

Constraint (blueprint:constraint)

Constraints are embedded in an attribute under the link relation blueprint:constraint.

Field Applies to Type Description
type all string Constraint type; see below
values allowed-values array List of allowed values for the attribute

Following constraint types are supported:

Constraint type Description
required The attribute must have a value and cannot be null.
unique The attribute value must be unique across all entities of this type.
allowed-values The attribute value must be one of a predefined set of allowed values.
created-date The attribute is managed by the system and contains the creation timestamp.
created-by The attribute is managed by the system and contains the creator’s identity.
modified-date The attribute is managed by the system and contains the last modified timestamp.
modified-by The attribute is managed by the system and contains the last modifier’s identity.

Search Parameter (blueprint:search-param)

Search parameters are embedded in an attribute under the link relation blueprint:search-param. They describe the query parameters that can be used to filter on this attribute in the search template.

Field Type Description
name string Query parameter name
title string Human-readable title
type string Search type; see below

Following search parameter types are supported:

Search parameter type Description
exact-match Match the attribute value exactly (case-sensitive string comparison).
prefix-match Match the attribute value by prefix.
greater-than Match values greater than the specified value.
less-than Match values less than the specified value.
greater-than-or-equal Match values greater than or equal to the specified value.
less-than-or-equal Match values less than or equal to the specified value.
full-text Perform a full-text search on the attribute value.
Attribute with search parameters 
{
  "name": "pay_before",
  "title": "Pay before",
  "type": "date",
  "description": null,
  "readOnly": false,
  "required": true,
  "_embedded": {
    "blueprint:search-param": [
      {
        "name": "pay_before",
        "title": "Pay before",
        "type": "exact-match"
      },
      {
        "name": "pay_before~after",
        "title": "Pay before: After",
        "type": "greater-than"
      },
      [...]
    ]
}

Relation (blueprint:relation)

Relations are embedded in the entity profile under blueprint:relation.

Field Type Description
name string Relation name
title string Human-readable title
description string or null Relation description
many_source_per_target boolean Multiple source entities can reference the same target
many_target_per_source boolean Source can reference multiple targets
required boolean Whether the relation is required

Each relation has a blueprint:target-entity link, referencing to the profile of the target entity type.

Relation 
{
  "name": "supplier",
  "title": "Supplier",
  "description": null,
  "many_source_per_target": true,
  "many_target_per_source": false,
  "required": false,
  "_links": {
    "blueprint:target-entity": {
      "href": "https://app.contentgrid.example/profile/suppliers",
      "title": "Supplier"
    }
  }
}

Templates

The entity profile provides HAL-FORMS templates that describe how to search and create entities of this type. See HAL-FORMS extensions for additional details on the extensions used.

search Template

The search template describes how to filter and sort the entity collection.

Search template properties are composed from 3 sources:

  • search parameters defined on attributes
  • Cross relation search parameters, where the search parameters from the relation target entity are prefixed by the relation name and a dot (e.g. supplier.name)
  • Special properties: _sort

The _sort property is a special property with a list of options. Next to the standard options as defined in HAL-FORMS, each option has property and direction fields. These additional fields can be used to programmatically select an option for a particular attribute and a particular sorting direction without having to resort to string manipulation.

search template 
{
  "_templates": {
    "search": {
      "method": "GET",
      "target": "https://app.contentgrid.example/invoices",
      "properties": [
        {
          "name": "pay_before",
          "prompt": "Pay before",
          "type": "date"
        },
        [...]
        {
          "name": "supplier.name",
          "prompt": "Supplier: Name",
          "type": "text"
        },
        {
          "name": "_sort",
          "prompt": "Sort",
          "type": "text",
          "options": {
            "minItems": 0,
            "promptField": "prompt",
            "valueField": "value",
            "inline": [
              {
                "property": "pay_before",
                "direction": "asc",
                "prompt": "Pay before ascending",
                "value": "pay_before,asc"
              },
              {
                "property": "pay_before",
                "direction": "desc",
                "prompt": "Pay before descending",
                "value": "pay_before,desc"
              },
              {
                "property": "total_amount",
                "direction": "asc",
                "prompt": "Total amount 0\u21929",
                "value": "total_amount,asc"
              },
              {
                "property": "total_amount",
                "direction": "desc",
                "prompt": "Total amount 9\u21920",
                "value": "total_amount,desc"
              }
            ]
          }
        }
      ]
    }
  }
}

create-form Template

The create-form template describes how to create a new entity of this type.

Depending on whether content attributes are present, the form can use application/json or multipart/form-data content types.

The create form includes fields for both attributes and relations, following the HAL-FORMS extensions specification.

create-form template 
{
  "_templates": {
    "create-form": {
      "method": "POST",
      "target": "https://app.contentgrid.example/invoices",
      "contentType": "multipart/form-data",
      "properties": [
        {
          "name": "received",
          "prompt": "Received",
          "required": true,
          "type": "date"
        },
        {
          "name": "document",
          "prompt": "Document",
          "type": "file"
        },
        {
          "name": "pay_before",
          "prompt": "Pay before",
          "required": true,
          "type": "date"
        },
        {
          "name": "total_amount",
          "prompt": "Total amount",
          "required": true,
          "type": "number"
        },
        {
          "name": "supplier",
          "prompt": "Supplier",
          "type": "url",
          "options": {
            "link": {
              "href": "https://app.contentgrid.example/suppliers",
              "title": "Suppliers"
            },
            "minItems": 0,
            "maxItems": 1,
            "valueField": "/_links/self/href"
          }
        }
      ]
    }
  }
}