simon/dog-and-duck
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
dog-and-duck/doc/Validation_Faults.md

2.8 KiB
Raw Blame History

Validation Faults in ActivityPub documents

Motivation

This document is intended to provide an extension vocabulary for ActivityStreams documents, which provides vocabulary for categorising and describing faults in ActivityPub documents.

The motivation is to be able to serialise a validation report on an ActivityPub document as an ActivityStreams document.

Intepretation

Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

'the spec'

Where the phrase 'the spec' is used in this document, it refers to a concatenation of the ActivityStreams specification and the ActivityPub specification.

The Fault object type

The Fault object type is a novel object type introduced by this document to describe validation faults. Objects with the Fault object type MUST have at least the following fields (additional fields are not required but are optional):

  1. :@context whose value shall be the URL of a document specifying this vocabulary;
  2. :type whose value shall be Fault;
  3. :severity whose value shall be one of minor, should, must or critical;
  4. :fault whose value shall be a unique token representing the particular fault type;
  5. :narrative whose value shall be a natural language description of the fault type.

The Fields

Context

The value of the @context field of a fault report object shall be the URL of this document, currently https://simon-brooke.github.io/dog-and-duck/codox/Validation_Faults.html.

Type

The value of the type field of a fault report object MUST be Fault.

Severity

Each fault report object MUST have a severity field whose value MUST be one of

  1. :info things which are not actuallys fault, but issues noted during validation;
  2. :minor things which I consider to be faults, but which don't actually breach the spec;
  3. :should instances where the spec says something SHOULD be done, which isn't;
  4. :must instances where the spec says something MUST be done, which isn't;
  5. :critical instances where I believe the fault means that the object cannot be meaningfully processed.

Fault

Unique codes shall be assigned to each fault type, and shall be documented in this section.

It is intended that there should ultimately be a well known site at which the fault codes can be resolved to natural language explanations in as many natural languages as possible of the nature of the particular fault.