Extending
When a document extends another and does not supply a value for a common property, the extending document will inherit its property value from the property of the document it extends.
This works similarly to default values.
In the same way that if a default value is changed, all documents using that default value will receive the value change. Documents inheriting values will see value changes for those properties where the extended document changes their inherited values.
Configuration
Documents toggle if they extend another document through an $extends source property.
This is assigned in your schema for the document in any data modifying endpoint you wish to control this on, for example, POST/PUT/PATCH.
In JSON schema, assigning the source property type to a property named extends looks like this:
"extends": {
"x-datastore-source": "document.$extends"
},Extending a document
Once an extends source property exists, to change the document a document extends, set the value of the $extends source property to be the document path of the document you wish to extend.
For example, if you want to extend a document with the URL https://us-c6812cbc.datastore.squiz.cloud/collection/my-document, you would set the path /collection/my-document as the property value for the extends property.
If this document to extend does not exist, this will result in a 400 Bad Request response code and the following JSON body:
[
“title”: “Invalid extending document”,
“Status”: 400,
“invalid-params”: {
“name”: “Extends”,
“reason”: “Document to extend does not exist”,
}
]A document can extend a document that already extends another document.
Additionally, more than one document can extend the same document.
This enables trees of related documents.
Changing extending document
If you want to change the document a document extends, change the extends source property value to a different document path.
If you want to extend any document no longer, then you change the extends source property value to a blank string.
Property value inheritance
When a document extends another, a property value will be inherited if:
-
The document extending another has not set a property value for a property
-
The property name and type are the same between the two documents
-
The document being extended has set a property value to be inherited. Default values will not be inherited.
When an inherited property value changes in a document being extended, all documents inheriting that value will change.
As when default values change in your schema when a document’s inherited property values change, this does not update that document’s updated DateTime source property value.
When a document extends a document that extends another document, values can be inherited from either extended document. The value a document inherits for a property is determined by which document has the closest relationship in the direct chain of inheritance.
Other source properties
It can be challenging to keep track of what documents a document extends or what documents are extending a document. Three related source properties are available to help.
These can be defined in your data schema alongside your $extends source property.
These property values are determined by the document relationships in place and cannot be directly set.
| Source Property | Description | Default value | Source property code |
|---|---|---|---|
$extendsAll |
An ordered array of documents I extend, with the first element being the immediate document I extend. |
Empty array |
document.$extendsAll |
$extendedBy |
The document paths as an alphabetically sorted array that immediately extend me |
Empty array |
document.$extendedBy |
$extendedByAll |
The document paths as an alphabetically sorted array that extend me either immediately or not |
Empty array |
document.$extendedByAll |
Security
For a document to be allowed to extend another and so inherit its property values, the modifying request must satisfy read access to the document that is desired to be extended.
Read access is defined by the ACL rule on the document path’s GET method.
Attempts to extend a document without read access will result in a 403 Forbidden response code and the following JSON body:
[
“title”: “Write access denied”,
“reason”: “Do not have read access to the extending document”
]Once two documents are connected, this relationship remains regardless of any ACL rule changes that may be made later.
Limitations
There are several limitations of the extends feature:
-
No single document may be extended by more than 500 documents, either directly or indirectly.
-
A document cannot directly or indirectly extend itself.
-
A document can only extend a single document.
-
Default values are not inherited from documents a document extends.