-
Notifications
You must be signed in to change notification settings - Fork 14
NNNN-property-registry #90
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
janvanmansum
wants to merge
2
commits into
OCFL:main
Choose a base branch
from
DANS-KNAW:NNNN-property-registry
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,2 @@ | ||
| *~ | ||
| /.idea |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,183 @@ | ||
| # OCFL Community Extension NNNN: Property Registry | ||
| ================================================== | ||
|
|
||
| * **Extension Name:** property-registry | ||
| * **Authors:** Linda Reijnhoudt, Jan van Mansum | ||
| * **Minimum OCFL Version:** 1.0 | ||
| * **OCFL Community Extensions Version:** 1.0 | ||
| * **Obsoletes:** n/a | ||
| * **Obsoleted by:** n/a | ||
|
|
||
| Overview | ||
| -------- | ||
|
|
||
| This extension facilitates a way to define properties for an OCFL object. The registry described here only maintains a list of properties that could be used, | ||
| and their definitions and structures. It does not prescribe how these properties are associated with items in the repository, such as object versions. One way | ||
| to associate properties with object versions is to use | ||
| the [NNNN-object-version-properties extension](./NNNN-object-version-properties.md). <!-- pending approval of this extension --> | ||
|
|
||
| Parameters | ||
| ---------- | ||
|
|
||
| Configuration is done by setting values in the file `config.json` at the top level of the extension's directory. The expected keys are: | ||
|
|
||
| - Name: `extensionName` | ||
| - Description: String identifying the extension. | ||
| - Type: String. | ||
| - Constraints: Must be `property-registry`. | ||
| - Default: `property-registry`. | ||
|
|
||
| - Name: `propertyRegistry` | ||
| - Description: An object with as keys the names of the properties, and as values property description entries as defined below. | ||
| - Type: Object. | ||
| - Constraints: The values must have at least the required properties as described below, at most extended with the optional properties. | ||
| - Default: Empty array. | ||
|
|
||
| ### Property description values | ||
|
|
||
| - Name: `description` | ||
| - Description: A human-readable description of the property, explaining its purpose and usage. | ||
| - Type: String. | ||
| - Constraints: None. | ||
| - Required: true. | ||
| - Default: None. | ||
|
|
||
| - Name: `type` | ||
| - Description: The JSON type of the property. | ||
| - Type: String. | ||
| - Constraints: Must be one of: `number`, `string`, `boolean` or `object`. If `object`, the property must have a `properties` key defined. | ||
| - Required: true. | ||
| - Default: `string`. | ||
|
|
||
| - Name: `constraints` | ||
| - Description: A human-readable description of the constraints on the property value, if any. | ||
| - Type: String. | ||
| - Constraints: None. | ||
| - Required: false. | ||
| - Default: None. | ||
|
|
||
| - Name: `properties` | ||
| - Description: If the property is of type `object`, this key must be present and contain an object that has as keys the names of the properties of the | ||
| object, | ||
| and as values property description values as defined in this paragraph. | ||
| - Type: Object. | ||
| - Constraints: Each value in the object must be a property description value as defined in this paragraph. | ||
| - Required: if `type` is `object`. | ||
| - Default: None. | ||
|
|
||
| - Name: `required` | ||
| - Description: A boolean indicating whether this property is required. | ||
| - Type: Boolean. | ||
| - Constraints: None. | ||
| - Required: false. | ||
| - Default: false. | ||
|
|
||
| - Name: `default` | ||
| - Description: The default value for the property, if any. | ||
| - Type: Any valid JSON value of the type defined by the `type` key. | ||
| - Constraints: Must be a valid value for the property type. May not be present if `required` is true. | ||
| - Required: false. | ||
| - Default: None. | ||
|
|
||
| Note, that the `array` type is not supported, as this would make validation of the property values more complex. The properties defined by means of this | ||
| extension are intended to be fairly simple, and not to be used for complex data structures, which are better stored in the content files of the OCFL object. | ||
|
|
||
| Note also, that this extension does not define a generic way to validate the property values against the constraints. | ||
|
|
||
| Implementation | ||
| -------------- | ||
|
|
||
| ### Validation | ||
|
|
||
| As part of the validation of the storage root, implementing software must check that the `config.json` is well-formed and contains the required keys and values | ||
| as described above. It must also check that no other keys are present in the `config.json` file. | ||
|
|
||
| ### Registering a property with the property registry | ||
|
|
||
| In order to register a property with the property registry, the implementing software must update the `config.json` file in the `property-registry` extension | ||
| directory with a new property description entry. | ||
|
|
||
| Examples | ||
| -------- | ||
|
|
||
| The following example registry contains three properties, each demonstrating a different use case. The registry is stored in the `property-registry/config.json` | ||
| file in the `extensions/property-registry` directory of the OCFL storage root. | ||
|
|
||
| ```text | ||
| [storage_root] | ||
| ├── 0=ocfl_1.0 | ||
| ├── ocfl_1.0.txt | ||
| ├── ocfl_layout.json | ||
| ├── property-registry.md | ||
| ├── extensions | ||
| | └── property-registry/ | ||
| | └── config.json | ||
| ``` | ||
|
|
||
| with the following content for `property-registry/config.json`: | ||
|
|
||
| ```json | ||
| { | ||
| "extensionName": "property-registry", | ||
| "propertyRegistry": { | ||
| "retentionEndDate": { | ||
| "description": "the date until which this object version may be retained in this repository", | ||
| "type": "string", | ||
| "constraint": "a date in ISO 8601 format, e.g. 2030-10-01", | ||
| "required": false | ||
| }, | ||
| "deaccessioned": { | ||
| "description": "If present, this version of the object has been deaccessioned and should not be disseminated", | ||
| "type": "object", | ||
| "required": false, | ||
| "properties": [ | ||
| { | ||
| "name": "datetime", | ||
| "description": "The date on which this object version has been deaccessioned", | ||
| "type": "string", | ||
| "constraint": "a datetime in ISO 8601 YYYY-MM-DDTHH-mm-ss format", | ||
| "required": true | ||
| }, | ||
| { | ||
| "name": "reason", | ||
| "description": "The reason why this object version has been deaccessioned.", | ||
| "type": "string", | ||
| "required": true | ||
| } | ||
| ] | ||
| } | ||
| }, | ||
| "packagingFormat": { | ||
| "description": "The packaging format of the current object version, as defined in the packaging-format-registry", | ||
| "type": "string", | ||
| "required": true | ||
| }, | ||
| "personalDataPresent": { | ||
| "description": "Indicates whether this object version contains personal data", | ||
| "type": "string", | ||
| "constraint": "One of: 'yes', 'no', 'unknown'", | ||
| "required": false, | ||
| "default": "unknown" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### `retentionEndDate` property | ||
|
|
||
| This is a simple string property that indicates the date until which this object version must be retained in the repository. It is required and must be in ISO | ||
| 8601 format. | ||
|
|
||
| ### `deaccessioned` property | ||
|
|
||
| This is a structured property that doubles as a boolean flag. If present, it indicates that this object version has been deaccessioned and should not be | ||
| disseminated. It also documents the date and reason for deaccessioning. | ||
|
|
||
| ### `packagingFormat` property | ||
|
|
||
| This is a simple string property that indicates the packaging format of the current object version as defined in | ||
| the [NNNN-packaging-format-registery extension](./NNNN-packaging-format-registry.md) <!-- pending approval of this extension -->. It is required and must be a | ||
| valid packaging format name as defined in that registry. | ||
|
|
||
| ### `personalDataPresent` property | ||
|
|
||
| This is a simple string property that indicates whether this object version contains personal data. It is not required and defaults to "unknown". | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This leaves the timezone undefined. The rest of the OCFL specification uses the RFC3339 profile of ISO8601, see e.g. https://ocfl.io/1.1/spec/#version