Specification of validator error codes and messages

[zimeon]

Rather than use the wiki to draft a set of error codes, I think we should start off with something machine readable. A JSON-LD file that can easily be extended for multilingual support might be good and we could use something as simple as:

{
  "@context": {
    "@version": 1.1,
    "id": "@id",
    "type": "@type",
    "@base": "https://ocfl.io/terms/validation/",
    "ocflv": "https://ocfl.io/terms/validation/",
    "errors": "ocflv:errors",
    "warnings": "ocflv:warnings",
    "info": "ocflv:info",
    "code": "@id",
    "section": "ocfl:section",
    "description": { "@id": "ocflv:description", "@container": "@language" }
  },
  "id": "ocflv:validation_codes",
  "errors": [
    {
      "code": "e001",
      "section": "https://ocfl.io/draft/spec/#object-conformance-declaration",
      "description": {
         "en": "Missing OCFL Namaste file",
         "zz": "Description in language zz"
      }
    },
    {
      "code": "e002",
      "section": "https://ocfl.io/draft/spec/#object-conformance-declaration",
      "description": {
         "en": "Namaste file name does not match OCFL Version"
      }
    }
  ]
}

and so on with blocks for "warnings" and "info". Something like this would be easy to use in code and also not too horrible as JSON-LD/RDF. We'd need to think a bit about how to maintain references to the specification but it would be quite easy to cut a version by putting the x.y in place of draft or lastest.

[zimeon]

Can check triples for above in https://json-ld.org/playground-dev/

[ahankinson]

Can we use the wiki to list the error codes, and then write them up in JSON?

[ahankinson]

How do you imagine this working with a validator? Would it take this file as input? Would this mean the logic of figuring out the violation would be in software, but the error to raise would be in the configuration?

[ahankinson]

But, in general, +1 to the suggestion!

[ahankinson]

Also, how does this fit WRT JSON-Schema?

[zimeon]

If I do any work on a validator I want to code only e001 etc. and then have a lookup for the text, hence the suggestion.

I'm not JSON-Schema expert but I think it would be trivial to write one for this if desired.

I think having the data in the code rather than the wiki is better because then we can use issues/PRs etc..

[ahankinson]

Yeah, I'm in favour of having it in some sort of parse-able medium. I was just writing them on the wiki so that we can figure out what we need. I don't see them as the end-point (although it may be useful to generate some sort of human-readable list of error messages).

I'm just trying to figure out the mechanics.

[zimeon]

Not intended as an answer to the above but maybe better to index by code instead, and type as Error/Warning/etc.:

{
  "@context": {
    "@version": 1.1,
    "id": "@id",
    "type": "@type",
    "@base": "https://ocfl.io/terms/validation/",
    "ocflv": "https://ocfl.io/terms/validation/",
    "Error": "ocflv:Error",
    "Warning": "ocflv:Warning",
    "Info": "ocflv:Info",
    "codes": {"@id": "ocflv:code", "@container": "@id"},
    "section": "ocfl:section",
    "description": { "@id": "ocflv:description", "@container": "@language" }
  },
  "id": "ocflv:validation_codes",
  "codes": {
    "e001": {
      "type": "Error",
      "section": "https://ocfl.io/draft/spec/#object-conformance-declaration",
      "description": {
         "en": "Missing OCFL Namaste file",
         "zz": "Description in language zz"
      }
    },
    "e002": {
      "type": "Error",
      "section": "https://ocfl.io/draft/spec/#object-conformance-declaration",
      "description": {
         "en": "Namaste file name does not match OCFL Version"
      }
    }
  }
}

[ahankinson]

Yeah, that's better.

[ahankinson]

Thinking further on this, I'm inclined to list out the error messages in the wiki first. It will be good to know whether we can match up what we think is an error with what we say in the spec (and identify any omissions either way).

Since the structure of the machine readable representation of these is still in flux, it would be good to save that until we can focus on software development and tooling. But I think this is definitely something we should do, and something we should write into the core of any validator(s).

[zimeon]

OK, will mark defer for now. I'm working with the format in #144 (comment) for some trial work on validation at https://github.com/zimeon/ocfl-py/blob/master/ocfl/data/validation-errors.jsonld

[zimeon]

Editors' discussion 2019-07-16 -- going to close this for now and instead focus on the simple list of error code for v1.0 and validator https://github.com/OCFL/spec/wiki/OCFL-Validators