62 lines
2.8 KiB
Markdown
62 lines
2.8 KiB
Markdown
# Validation Faults in ActivityPub documents
|
|
|
|
## Motivation
|
|
|
|
This document is intended to provide an extension vocabulary for [ActivityStreams](https://www.w3.org/TR/activitystreams-core/) documents, which provides vocabulary for categorising and describing faults in [ActivityPub](https://www.w3.org/TR/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
|
|
|
|
0. `:info` things which are not actuallys fault, but issues noted during
|
|
validation;
|
|
1. `:minor` things which I consider to be faults, but which
|
|
don't actually breach the spec;
|
|
2. `:should` instances where the spec says something SHOULD
|
|
be done, which isn't;
|
|
3. `:must` instances where the spec says something MUST
|
|
be done, which isn't;
|
|
4. `: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.
|