Skip to content

Commit

Permalink
Add 'Optional Extension Initializer' (#36)
Browse files Browse the repository at this point in the history
* Add 'Optional Extension Initializer'

Resolves: #34

* code review

* typo

* code review

* code review

* code review

Co-authored-by: Andrew Woods <awoods@duraspace.org>
  • Loading branch information
Andrew Woods and Andrew Woods authored Nov 17, 2020
1 parent 14da983 commit 71d1f88
Showing 1 changed file with 17 additions and 3 deletions.
20 changes: 17 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,23 @@ To use OCFL extensions you first need an OCFL client that supports the desired e

Reference the OCFL specification'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"
Expand All @@ -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
Expand Down

0 comments on commit 71d1f88

Please sign in to comment.