diff --git a/oxa-human-readable.md b/oxa-human-readable.md deleted file mode 100644 index 6559f6f..0000000 --- a/oxa-human-readable.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "**DRAFT**: Declaring OXA representations from human-readable outputs" -date: 2025-11-10 -author: Carlos Scheidegger -license: "CC BY 4.0" ---- - -## Intro - -Documents that want to declare that they're "human-readable representations" of OXA documents can use a set of format-specific metadata annotations, depending on the document mimetype. - -## Mimetypes - -### `text/html` - -An HTML document that wants to declare an OXA representation can do one of the following: - -- include a `meta` element in the `head` block with `name="oxa-document-uri"` and `value` being the URI of an HTTP resource representing the OXA document -- include a `meta` element in the `head` block with `name="oxa-reference-uri"` and `value` being the URI of an HTTP resource representing the [OXA reference](./oxa-references.md). -- include a `meta` element in the `head` block with `name="oxa-document"` and `value` being the JSON representation of the OXA document. -- include a `meta` element in the `head` block with `name="oxa-reference"` and `value` being the JSON representation of the [OXA reference](./oxa-references.md). - -### `image/png` - -A PNG image that wants to declare an OXA representation can do one of the following: - -- include an `tEXt` ancillary chunk with keyword `JSON:dev.oxa:oxa-document-link` and UTF-8 text with the URI of an HTTP resource representing the OXA document -- include an `tEXt` ancillary chunk with keyword `JSON:dev.oxa:oxa-reference` and UTF-8 text with the URI of an HTTP resource representing the [OXA reference](./oxa-references.md). -- include an `tEXt` ancillary chunk with keyword `JSON:dev.oxa:oxa-document` and UTF-8 text containing the JSON representation of the OXA document. -- include an `tEXt` ancillary chunk with keyword `JSON:dev.oxa:oxa-reference` and UTF-8 text containing the JSON representation of the [OXA reference](./oxa-references.md). diff --git a/oxa-references.md b/oxa-references.md deleted file mode 100644 index 19fd307..0000000 --- a/oxa-references.md +++ /dev/null @@ -1,112 +0,0 @@ -# OXA Links - -## Motivation - -Document authoring systems such as [Quarto](https://quarto.org) and [Myst](https://mystmd.org/) want the ability to retrieve JSON representations of existing documents in a machine-readable form. - -## Terminology - -In this document, uppercase phrases are used according to [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). - -## Spec - -### JSON object equality - -When comparing two JSON objects, this spec uses the word "equals" to mean two objects that are the same according to the [SameValueZero algorithm in the ECMA 262 spec](https://tc39.es/ecma262/multipage/abstract-operations.html#sec-samevaluezero). - -### Canonical Hashes - -In this document, the "canonical hash" of a JSON object, given a hashing function, is a JSON object that satisfies the following JSON schema - -```json -{ - "type": "object", - "required": ["function", "hash"], - "properties": { - "function": { - "type": "string", - "enum": ["SHA-256", "SHA-512", "SHA3-256", "SHA3-512"] - }, - "hash": { - "type": "string", - "pattern": "^[a-fA-F0-9]+$" - } - }, - "additionalProperties": false -} -``` - -The field `hash` encodes the hexadecimal digits of result of running the hash function `function` on the canonical version (cf. [RFC 8785](https://datatracker.ietf.org/doc/html/rfc8785)) of a JSON object. - -### JSON Interop Object - -A JSON document that respects the following spec will be referred to as "a JSON interop object". - -A JSON interop object MUST be a JSON object (RFC-8259) that respects the following JSON schema: - -``` -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "required": ["schemaHash", "contentHash"], - "definitions": { - "hashObject": { - "type": "object", - "required": ["function", "hash"], - "properties": { - "function": { - "type": "string", - "enum": ["SHA-256", "SHA-512", "SHA3-256", "SHA3-512"] - }, - "hash": { - "type": "string", - "pattern": "^[a-fA-F0-9]+$" - } - }, - "additionalProperties": false - } - }, - "properties": { - "schemaHash": { - "$ref": "#/definitions/hashObject" - }, - "contentHash": { - "$ref": "#/definitions/hashObject" - }, - "schema": { - "$ref": "http://json-schema.org/draft-07/schema#" - } - "schemaHref": { - "type": "string", - "format": "uri" - }, - "contentHref": { - "type": "string", - "format": "uri" - } - } -} -``` - -The `schemaHash` field MUST equal the canonical hash of a JSON object representing some JSON schema. - -The `contentHash` field MUST equal the canonical hash of some JSON object. - -If the `schema` field is present, it MUST contain a JSON object whose canonical hash equals the value in the `schemaHash` field. - -If the `content` field is present, it MUST contain a JSON object whose canonical hash equals the value in the `contentHash` field. - -If the `schemaHref` field is present, then an HTTP GET request issued against the URI referenced SHOULD respond with an `application/json` object whose canonical hash equals the value in the `schemaHash` field. - -If the `contentHref` field is present, then an HTTP GET request issued against the URI referenced SHOULD respond with an `application/json` object whose canonical hash equals the value in the `contentHash` field. - -## Authors - -- Rowan Cockett - Curvenote -- Franklin Koch - Curvenote -- Carlos Scheidegger - Posit, PBC -- Nokome Bentley - Stencila - -## versions - -- 0.0.1: 2025-11-07 diff --git a/oxa-types.json b/oxa-types.json deleted file mode 100644 index 38ad675..0000000 --- a/oxa-types.json +++ /dev/null @@ -1,654 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://github.com/scientific-publishing-tools-meeting/schema/oxa-types.json", - "title": "OXA Types Schema", - "description": "JSON Schema for OXA document types", - "definitions": { - "Attr": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "classes": { - "type": "array", - "items": { - "type": "string" - } - }, - "data": { - "type": "object", - "additionalProperties": true - } - }, - "required": ["classes", "data"] - }, - "QuoteMark": { - "type": "string", - "enum": ["Single", "Double"] - }, - "Text": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Text" - }, - "value": { - "type": "string" - } - }, - "required": ["type", "value"] - } - ] - }, - "Strong": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Strong" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Emphasis": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Emphasis" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Strikeout": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Strikeout" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Superscript": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Superscript" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Subscript": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Subscript" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "SmallCaps": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "SmallCaps" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Underline": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Underline" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Span": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Span" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "InlineQuote": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "InlineQuote" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - }, - "mark": { - "$ref": "#/definitions/QuoteMark" - } - }, - "required": ["type", "children", "mark"] - } - ] - }, - "DisplayMath": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "DisplayMath" - }, - "value": { - "type": "string" - } - }, - "required": ["type", "value"] - } - ] - }, - "InlineMath": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "InlineMath" - }, - "value": { - "type": "string" - } - }, - "required": ["type", "value"] - } - ] - }, - "Image": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Image" - }, - "uri": { - "type": "string" - }, - "title": { - "type": "string" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "uri", "title", "children"] - } - ] - }, - "Link": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Link" - }, - "uri": { - "type": "string" - }, - "title": { - "type": "string" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "uri", "title", "children"] - } - ] - }, - "Citation": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "mode": { - "type": "string", - "enum": ["AuthorInText", "SuppressAuthor", "NormalCitation"] - }, - "prefix": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - }, - "suffix": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["mode", "prefix", "suffix"] - } - ] - }, - "Cite": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Cite" - }, - "citations": { - "type": "array", - "items": { - "$ref": "#/definitions/Citation" - } - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "citations", "children"] - } - ] - }, - "Inline": { - "oneOf": [ - { - "$ref": "#/definitions/Cite" - }, - { - "$ref": "#/definitions/DisplayMath" - }, - { - "$ref": "#/definitions/Emphasis" - }, - { - "$ref": "#/definitions/Image" - }, - { - "$ref": "#/definitions/InlineMath" - }, - { - "$ref": "#/definitions/Link" - }, - { - "$ref": "#/definitions/InlineQuote" - }, - { - "$ref": "#/definitions/SmallCaps" - }, - { - "$ref": "#/definitions/Span" - }, - { - "$ref": "#/definitions/Strikeout" - }, - { - "$ref": "#/definitions/Strong" - }, - { - "$ref": "#/definitions/Subscript" - }, - { - "$ref": "#/definitions/Superscript" - }, - { - "$ref": "#/definitions/Text" - }, - { - "$ref": "#/definitions/Underline" - } - ] - }, - "Paragraph": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Paragraph" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Plain": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Plain" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Div": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Div" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Block" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "BlockQuote": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "BlockQuote" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Block" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Heading": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Heading" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - }, - "level": { - "type": "integer", - "minimum": 1 - } - }, - "required": ["type", "children", "level"] - } - ] - }, - "CodeBlock": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "CodeBlock" - }, - "value": { - "type": "string" - } - }, - "required": ["type", "value"] - } - ] - }, - "Section": { - "allOf": [ - { - "$ref": "#/definitions/Attr" - }, - { - "type": "object", - "properties": { - "type": { - "const": "Section" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Block" - } - } - }, - "required": ["type", "children"] - } - ] - }, - "Block": { - "oneOf": [ - { - "$ref": "#/definitions/Section" - }, - { - "$ref": "#/definitions/BlockQuote" - }, - { - "$ref": "#/definitions/CodeBlock" - }, - { - "$ref": "#/definitions/Div" - }, - { - "$ref": "#/definitions/Heading" - }, - { - "$ref": "#/definitions/Paragraph" - }, - { - "$ref": "#/definitions/Plain" - } - ] - }, - "Document": { - "type": "object", - "properties": { - "metadata": { - "type": "object", - "additionalProperties": true - }, - "title": { - "type": "array", - "items": { - "$ref": "#/definitions/Inline" - } - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Block" - } - } - }, - "required": ["metadata", "title", "children"] - } - }, - "$ref": "#/definitions/Document" -}