• Menu

    Model Configuration

    HCMS is based on a JSON model configuration. Its intent is to define from a JSON configuration an API usable by any of your client applications (often single page applications).

    TIP

    pages about the environment setup - datasource, server, ... - are on the configuration deployment pages.

    Get completion

    Before starting to dig into the model itself, it is important to be properly setup. As soon as you get an IDE/editor with JSON schema support/completion you can just create a documentation (model.json) and inject the schema reference in it: JSON-Schema .

    Here is a basic document: 

    {
    "$schema": "https://www.yupiik.io/hcms/schema/model.jsonschema.json"
}

    Configuration concept

    The configuration is focused on two concepts:

    1. Entities,

    2. JSON-RPC mapping.

    The entity (a.k.a. EntitySpec) defines what is an entity - columns, how it is mapped to SQL and what is allowed or not on it.

    The JSON-RPC mapping just links an entity to JSON-RPC method(s). For example linking an entity to a JSON-RPC type CRUD will define the methods $entity.findById, $entity.findAll, $entity.create, $entity.update, $entity.deleteById.

    TIP

    since JSON-RPC supports bulking (send multiple requests as arrays), the findById method is also optimized when there are only findById sent at once enabling to do a single SQL query to load them all and still comply to JSON-RPC contract.

    Configuration reference

    HCMS Model Schema

    Name Type Nullable Description
    enableOpenAPI boolean true

    Should /openapi.json endpoint be enabled.
    enableOpenRPC boolean true

    Should /openrpc.json endpoint be enabled.
    enableSwaggerUI boolean true

    Should /swagger-ui/ endpoint be enabled, ensure to also set enableOpenAPI to true.
    entities array with items of type unknown false Entities to define and make available for JSON-RPC methods.
    jsonRpcMethods array with items of type unknown false JSON-RPC methods to register.
    partialOpenRPC

    object of type

    		true

    OpenRPC partial object, should generally set the info entry at least, likely servers and maybe externalDocs. See OpenRPC specification.
    sql

    array with items of type string

    		 false List of SQL scripts to execute at model load time.
    $schema string false -

    JsonRpcMethod schema

    Name Type Nullable Description
    description string true OpenRPC description.
    entityName string true Name of the entity to use to generate the JSON-RPC methods.
    security unknown true Security model for this method(s) registration(s). If not set, default is equivalent to anonymous access.
    type

    enum with potential values CRUD, FIND_ALL, CREATE, UPDATE, FIND_BY_ID, DELETE_BY_ID

    		 true Type of JSON-RPC method generation.

    ImplicitFiltering schema

    Name Type Nullable Description
    clause string true

    Filtering clause(s), ex: status = 'PUBLISHED' OR author = {{user.sub}}. The placeholders use handlebars syntax. user represents the contextual JWT.

    SecurityValidation schema

    Name Type Nullable Description
    anonymous boolean false Can anyone call the endpoint without any validation, not even a JWT.
    logged boolean false Can anyone authenticated call this endpoint - requires a valid JWT.
    roles

    array with items of type string

    		 false

    Requires one of this list roles to be in the roles of the JWT. At least one role from the JWT (roles array) must match this list of role if set. The values is considered as a constant - like user:admin. For dynamic filtering (like 'only find my posts'), prefer using entity filtering and the database directly.

    JsonSchema schema

    Name Type Nullable Description
    exclusiveMaximum integer true

    For numbers/integer.
    exclusiveMinimum integer true

    For numbers/integer.
    format

    enum with potential values date_time, time, date, duration, email, hostname, ipv4, ipv6, uuid, uri, json_pointer, regex

    		 true

    For string.
    items unknown true As of today defining an array is not supported, will come in the future.
    maxLength integer true

    For string.
    maximum integer true

    For numbers/integer.
    minLength integer true

    For string.
    minimum integer true

    For numbers/integer.
    multipleOf integer true

    For numbers/integer.
    pattern string true

    For string.
    properties

    object of type

    		true

    For objects, the properties - for entities ensure to use primitives as children.
    required

    array with items of type string

    		 false Required attributes for objects.
    type

    array with items of type string

    		 false

    Type for the schema, for entities it is normally object. This is a list to allow to create null to make it nullable.

    EntitySpec schema

    Name Type Nullable Description
    allowedSortKeys

    array with items of type string

    		 false

    List of (JSON) properties which are enabled to sort the findAll result set if enabled
    allowedWhereKeys

    array with items of type string

    		 false

    List of (JSON) properties which are enabled to filter the findAll result set if enabled (where clause)
    allowedWhereOperators

    array with items of type string

    		 false

    The where operators which can be used in filters payload for findAll methods if enabled, using default enables main database ones. Not setting it will only enable = by default. Text - like operator for example, is tested in lower case.
    autoGeneratedIds boolean false

    If true we consider the identifiers are generated at create time - ensure your DDL is accurate if so.
    generatedCreateFields

    object of type

    		true

    Field generated at create time. It is often used for audit (datetime) and id fields (uuid). Only relevant for CRUD method type.
    generatedUpdateFields

    object of type

    		true

    Field generated at update time. It is often used for audit (datetime). Only relevant for CRUD method type.
    identifierNames

    array with items of type string

    		 false

    List of properties representing the identifiers of the entity - JSON names, if ignored and properties has an id entry it will be used as identifier.
    implicitFiltering unknown true

    Implicit where clause entries, note that create will need to use security since there is no entity context there.
    jsonSchema unknown true Simplified JSON-Schema definition for the entity and JSON-RPC related endpoints.
    name string true Entity name - identifier.
    naming

    enum with potential values CAMEL_TO_SNAKE

    		 true How to transform properties name to get database names from JSON-RPC ones. No-op if ignored.
    revisionProperty string true

    Name of the field used to manage the versioning. If not set there is no revision (only a snapshot of the entity). If set the targetting field if should target either a number or a date (type=string and format=date-time) field. In such a case, the field is 100% managed by HCMS and is not writable by the client.
    tableName string true Database table name.
    validateWithJsonSchema boolean false

    For create and update endpoints if relevant, should they be validated with jsonSchema. In such a case only the named binding of JSON-RPC is supported, not the array mode. Also take care to virtual fields which will be validated too.

    JsonRpcMethodSecurity schema

    Name Type Nullable Description
    create unknown true

    Security for creation access (create endpoint).
    delete unknown true

    Security for deletion access (deleteById endpoint).
    update unknown true

    Security for creation access (update endpoint).
    view unknown true

    Security for view access (findById, findAll endpoints).

    EntityImplicitFiltering schema

    Name Type Nullable Description
    delete unknown true

    Where clause (without WHERE keyword) to add to delete, it can use user.xxx to access field xxx of the JWT if it is there (else null will be used).
    update unknown true

    Where clause (without WHERE keyword) to add to update, it can use user.xxx to access field xxx of the JWT if it is there (else null will be used).
    view unknown true

    Where clause (without WHERE keyword) to add to findById and findAll, it can use user.xxx to access field xxx of the JWT if it is there (else null will be used).

    Navigation