diff --git a/README.md b/README.md index 6dae72a..a0c0fc2 100644 --- a/README.md +++ b/README.md @@ -14,20 +14,23 @@ To use OCFL extensions you first need an OCFL client that supports the desired e Reference the OCFL specifications's description of [object extensions](https://ocfl.io/1.0/spec/#object-extensions) and [storage root extensions](https://ocfl.io/1.0/spec/#storage-root-extensions). -A *root extension directory* refers to the directory named `extensions` that is located in either the storage root or an object root. An *extension directory* is an extension specific directory that is the child of a root extension directory and named using the extension's *Registered Name*. For example, `extensions/0000-example-extension` is the extension directory for the extension [0000-example-extension](docs/0000-example-extension.md). +The OCFL storage root MAY contain a copy of an extension's specification. Each extension specification details how it should be implemented, but there are a few rules that apply to every extension. -The OCFL storage root MAY contain a copy of an extension's specification. +A *root extension directory* refers to the directory named `extensions` that is located in either the storage root or an object root. An *extension directory* is an extension specific directory that is the child of a root extension directory and MUST be named using the extension's *Registered Name*, or `initial` (see [Optional Initial Extension](#optional-initial-extension)). For example, `extensions/0000-example-extension` is the extension directory for the extension [0000-example-extension](docs/0000-example-extension.md). ### Configuration Files An extension's parameters are serialized as a JSON object and written to a configuration file named `config.json` within the extension's extension directory. +If an extension includes a configuration file, one of the properties in that file MUST be `extensionName`, where the value is the *Registered Name* of the extension. + For example, the extension [0000-example-extension](docs/0000-example-extension.md) could be parameterized as follows: ```json -{ +{ + "extensionName": "0000-example-extension", "firstExampleParameter": 12, "secondExampleParameter": "Hello", "thirdExampleParameter": "Green" @@ -45,6 +48,17 @@ It is conceivable that some extensions may not be compatible with other extensio Because OCFL clients are not required to implement any or all extensions, it is also possible that a client may encounter an extension that it does not implement. In these cases, it is up to the client to decide how to proceed. A client may fail on unsupported extensions, or it may choose to ignore the extensions and carry on. +### Optional Initial Extension + +A _root extension directory_ MAY optionally contain an _initial_ extension that, if it exists, SHOULD be applied before all other extensions in the directory. +An _initial extension_ is identified by the extension directory name "initial". + +An _initial extension_ could be used to address some of the [undefined behaviors](#undefined-behavior), define how extensions are applied, and answer questions such as: + + - Is an extension deactivated, only applying to earlier versions of the object? + - Should extensions be applied in a specific order? + - Does one extension depend on another? + ## Specifying Community Extensions ### Layout