HCMS core concepts Entities and schemas
Explains the core concepts behind HCMS
Custom data models
Headless CMS allows you to define your own content API. HCMS consumes and modifies data stored in the censhare system and can perform read and write operations on censhare assets, e.g., search assets or create new ones. The uniqueness of the HCMS design is that there is no standard API available, meaning, that there is no static data model either. However, there is no way to directly access assets as they are in censhare. This is solved though the basic concepts of HCMS: entities and schemas. Entities are views to censhare assets. Any modifications done on entities update censhare assets. One entity may represent only one asset, but, by including all (or selected) relationships of the asset, it may even represent the whole structures of assets.
Schemas
How to define an entity
Each entity is represented as a JSON document (instead of the XML format of the censhare Server).
A schema describes what this entity actually is. It is somtimes calles "entity type". Such JSON schemas define which properties and their types (string, number, object, array, etc.) are allowed in a given entity. You can say that schemas define how a censhare asset is translated into a JSON document, but this is not one-to-one translation. It is not necessary to include all properties and relationships from the corresponding censhare asset. On the other side, it is possible to represent the whole structures of assets in one entity by including also asset relationships in the entity that views to it.
Schema validation
On every read and write operation, HCMS will validate the entity (JSON object) using existing schemas. It will not accept an entity that fails the schema validation, e.g., cases when a property defined as mandatory in the schema is not present in the entity (the same for the wrong data format). This ensures data integrity.
Schema validation is done even on read operations; as a consequence, entities that fail schema validation will, e.g., never appear in a search result or be accessed by the application in any other way. The advantage is that the API consumer does not have to validate all returned invalid documents. By itself, the censhare Server does not enforce this kind of validation.
Which role schemas play
Schemas mainly serve the following purposes. They allow to define:
- application-specific interfaces
- mapping to the censhare storage model
Therefore, schemas translate one data model into another. It means that each feature, relationship, and asset type can be represented in a different way. This allows to re-use the same content for various purposes.
Custom business logic (business processes)
Any custom business logic of your application can be implemented through webhooks. Those are HTTP requests that are invoked when the entity is being modified. Webhooks call a remote URL. Webhooks are specified in the JSON schema of the entity and specify which operations are allowed. Other operations with the entity will be rejected even if the entity is otherwise validated. For more information on HCMS webhooks please check this article.
Multiple HCMS instances: sharing or segregating the data
Multiple HCMS instances can consume and modify data on the same censhare Server using different sets of schemas. All of this needs to be implemented directly in the censhare system by tagging assets with output channels. This design allows re-using data from the censhare Server in more than one application. As a consequence, the same asset can be served in different ways, e.g., with different permissions. It is also possible to do the opposite: to segregate data, so that certain assets are only accessible for certain HCMS instances.
How to create schemas
Please refer to this article.