Parameterising Extensions

[neilsjefferies]

Extensions may have a number of options describing functional variants. We need to define an mechanism to allow extensions to have parameters that cirscumscribe these options. These should be both human readable within the extension definition but allow for the implementation of machine actionable mechanisms (via JSON and URL) for programmatic access. To this end parameters will be defined as a set of key-value pairs.

[pwinckles]

Are you imagining that extension parameters will be stored in files in the OCFL storage root? For example, let's say that there's an extension that describes an n-tuple storage layout. The draft spec currently states that the ocfl_layout.json should contain a key property that's value is:

A key identifying the precise arrangement of directories and OCFL objects under the storage root, i.e. how OCFL object identifiers are mapped to directory hierarchies. The value of this key is not defined in the OCFL specification, but MUST correspond to a value given in an Extension.

In this case, would the ocfl_layout.json looks something like:

{
  "key": "n-tuple-layout",
  "description": "n-tuple storage layout"
}

And in the storage root there's an additional file named something like extension-n-tuple-layout.json that looks something like this:

{
  "encoding" : "hash",
  "casing" : "lower",
  "digestAlgorithm" : "md5",
  "size" : 2,
  "depth" : 3,
  "encapsulation" : {
    "defaultString" : "obj",
    "type" : "id",
    "encoding" : "url"
  }
}

that encapsulates all of an extension's configuration as defined in the extension's spec?

Additionally, is there a need to support extension versioning? In the layout example, should ocfl_layout.json also include a version property? Or maybe as part of the key, eg n-tuple-layout-1.0?

[neilsjefferies]

My preference is to include extension parameters where the extension is referenced - so in the same file so it can't get mislaid. A parameterised extension reference without the parameters is of limited usefulness.
As far as versioning goes, my initial impulse is to say no. The spec as it stands states that extensions should stand alone rather than have dependencies on other extensions and versioning introduces a new dependency mechanism.

[neilsjefferies]

A first cut can be found at https://github.com/neilsjefferies/extensions (forked because everything got touched). NB. I don't mix identifer definitions with storage layout definitions in the examples given - which is what @pwinckles suggestion does. Identifiers are used in places other than storage layouts and should really be another namespace-y extension themselves. The digest extension is parameterised so code can quickly determine whether an OCFL contains digests it cannot handle.

[pwinckles]

So, in the case of ocfl_layout.json, you're saying that you can either create ocfl_layout.json like the following:

{
  "key": "0002-N-tuple-tree.md",
  "description": "n-tuple storage layout"
  "0002-N-tuple-tree.md": {
    "identifer length": 12,
    "case mapping": "ToLower",
    "invert mapping": "FALSE",
    "tuple size": 12,
    "number of tuples": 0,
    "short object root": "FALSE"
  }
}

Or create a file 0002-N-tuple-tree.json in the storage root that contains the following:

{
  "0002-N-tuple-tree.md": {
    "identifer length": 12,
    "case mapping": "ToLower",
    "invert mapping": "FALSE",
    "tuple size": 12,
    "number of tuples": 0,
    "short object root": "FALSE"
 }
}

Is that correct?

[neilsjefferies]

@pwinckles At the moment, yes - but we're still wrangling with the extension part of the spec so this may change. My expectation is that the second mechanism would be used for extensions with content in directories. NB. This is itself an extension and not part of the core spec!

[neilsjefferies]

Addressed by #8 and #9