Referencing extensions in ocfl_layout.json

[pwinckles]

When describing ocfl_layout.json, the draft OCFL spec reads:

key - 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.

The text is unclear what "value" the key must correspond to. Opening the issue here rather than under extensions because my assumption, which may be incorrect, is that the value it is supposed to correspond to is the file name of the extension (eg 0002-fixed-length-n-tuple-trees.md or 0002-fixed-length-n-tuple-trees) and that this should be clarified in the spec.

[awoods]

Good point, @pwinckles .
We should clarify what is meant by "a value given in an Extension".

[zimeon]

My understanding was that the intention was to have the value described explicitly in the extension and not necessarily related to the extension name. To be explicit, extension 0002-fixed-length-n-tuple-trees.md might have defined the term xyz-tuple-tree. Now we have the idea of parameters this seems disconnected.

Given, https://github.com/OCFL/extensions#referencing-parameters, perhaps ocfl_layout.json should be an object where each key is an extension filename and contains the parameterization. Maybe with an optional additional description? So, could be something like:

{
  "0000-example-extension.md": {  
     "firstExampleParameter": 12,  
     "secondExampleParameter": "Hello",  
     "thirdExampleParameter": "Green"  
  },
  "1234-other-extension.md": {
      "description": "no parameters for this one but here I describe how we've used it"  
  }
}

[pwinckles]

I think it would be desirable for extension ids/keys to be standardized outside individual extension specifications and additionally not equal to the name of the specification file.

For the first point, it is easier to create the necessary globally unique extension identifier if identifiers are not assigned arbitrarily within spec texts. It becomes burdensome to inspect each spec individually to see what identifier it's using.

For the second point, I do think the identifier should be part of the spec filename, but not equal to it. There are a couple reasons for this:

1. It allows the identifier to be easily used for naming related directories and files. For example, extensions/0000-example-extension/ and extensions/0000-example-extension/0000-example-extension.json
2. It avoids problems if we ever want to change the format that specs are written in.

The extension parameter text that you referenced is currently in an inconsistent state. Part of the language suggests that there are multiple ways to define extension parameters while at the same time stating that the only way to define parameters is through an accompanying json file. I believe it is like this because the inline parameters were removed after the inventory.json was clearly locked down.

The current text does not state that storage extension parameters may be defined in ocfl_layout.json, whether this is intended or not. I'm not sure if it's necessary to allow them -- a standard json file seems good enough. But, if the desire is to allow parameters to be defined in ocfl_layout.json, that is a good reason to keep the parameter spec. Otherwise, I don't think it's really necessary (OCFL/extensions#18).

[rosy1280]

Deferring by removing the paragraph (and subsequent bullet points) that begins with:

An OCFL Storage Root may contain a JSON file named......

We will create a new ticket outside the 1.0 milestone that refers to this and address this after the 1.0 release.

[pwinckles]

I strongly disagree with this change without a replacement mechanism for describing a repository's layout. How is a client supposed to know what to do? By scanning the extensions directory looking for a storage layout extension that it recognizes? What if there are multiple storage layout extensions in the extensions directory? I don't think something this important should be configured implicitly.

The problem here is not with ocfl_layout.json. It is not hard to make it work with the extensions. The problem is that the extensions themselves were never adequately described.

[rosy1280]

@pwinckles definitely appreciate your perspective, but by continuing to focus on clarifying extensions we'll never release 1.0. we will address this issue in #482

[pwinckles]

As currently defined, OCFL extensions are unusable. I appreciate wanting to get OCFL 1.0 released, and I appreciate the work you all have put into it, but I think it is a mistake to push it out the door without addressing a handful of problems with the extensions.

[edit] Probably not swaying any minds, but I'm only being difficult because I care.

[zimeon]

OK, change of mind in editors' discussion. We will change description of ocfl_layout.json to refer to a "registered extension name" (same language we use for object extensions) and the extensions text will define that (as, e.g., 0001-digest-algorithms though that doesn't apply to layouts). Also move optional ocfl_layout.json below the normative parts and change key to extension

[ahankinson]

@pwinckles we've reversed the decision to remove the ocfl_layout.json part of the spec. Your voice is always heard and appreciated!

We think that the extensions can evolve independently of the actual spec, so the push to get 1.0 out, and the work to improve the actual extensions mechanism can be decoupled. Understanding that the extensions should always define a superset of the OCFL spec, we're keen to not put any backwards dependencies on extensions back into the spec -- I think the ocfl_layout.json is one point where that separation is blurry, but for historical reasons it exists and we can look to remove it or further optimize it later when we can have a broader discussion about it.

[zimeon]

Definition of the "registered name" for an extension is added in OCFL/extensions#13

[pwinckles]

Thanks @ahankinson @zimeon @neilsjefferies!

@ahankinson I don't disagree that they should be decoupled. It just felt like there were a few things that needed to be addressed before for extensions to be minimally viable. I have no further objections apart from the clarification that @neilsjefferies is actively working on addressing.