Skip to content

Commit

Permalink
Use headers instead of definition lists
Browse files Browse the repository at this point in the history 
And add descriptions of the JSON types
  • Loading branch information
@theory
theory committed Jul 5, 2024
1 parent a69c30f commit 7035d0d
Showing 1 changed file with 125 additions and 93 deletions.
218 changes: 125 additions & 93 deletions spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,30 +10,29 @@
# RFC TBD
# PostgreSQL Extension Network Distribution Metadata Specification

## Abstract
## Abstract ##

This document describes version 2.0.0 of the PGXN distribution metadata
specification, also known as the "PGXN Meta Spec." PGXN Metadata ships with
PostgreSQL extension source distribution packages, and serves to describe the
extension for the benefit of automated indexing, distribution, full-text
search, binary packaging, and more.

## Status of This Memo
## Status of This Memo ##

This is an Internet Standards Track document.

This RFC represents the consensus of the distributed community of PostgreSQL
extension developes, distributors, and packagers, generally referred to as the
"PostgreSQL Extension Ecosystem". It is formatted using the [MultiMarkdown]
variant of [Markdown], and the canonical copy may always be found at
"PostgreSQL Extension Ecosystem". It is formatted using the [Github Flavored
Markdown] variant of [Markdown], and the canonical copy may always be found at
[master.pgxn.org/meta/spec.txt]. A generated HTML-formatted copy found at
[pgxn.org/spec/] may also be considered canonical.

Information about the current status of this document, any errata, and how to
provide feedback on it may be obtained from its [source code repository].


## Copyright Notice
## Copyright Notice ##

Copyright (c) 2010-2024 PGXN and the persons identified as the document
authors. All rights reserved.
Expand All @@ -43,128 +42,161 @@ This RFC is distributed under the [CC BY-SA 4.0] license.
Code Components extracted from this document MUST include the [PostgreSQL
License].

## Introduction
## Introduction ##

Distribution metadata describe important properties of PGXN source code
distributions. Tools that build PGXN source distribution archives should
create a metadata file in accordance with this specification and include it
with the distribution for use by automated tools that index, examine, package,
or install PGXN source distributions.

### Terminology
### Terminology ###

Source Code Package
: The primary object described by the metadata, also referred to as "source
package" and sometimes just "package". In the context of this document the
term refers to a collection of extensions, source code, utilities, tests,
and/or documents that are distributed together for other developers to
build, install, and use. Examples of source packages include [`semver`],
[`vector`], and [`citus`].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in [IETF RFC 2119].

Extension
: A software component that extends the capabilities of a PostgreSQL
database or cluster. Extensions may be `CREATE EXTENSION` [extensions],
[background workers], command-line apps, [loadable modules], shared
libraries, and more.
This document makes use of the following additional terms:

Consumer
: Code that reads a metadata file, deserializes it into a data structure in
memory, or interprets a data structure of metadata elements.
#### Package ####

Producer
: Code that constructs a metadata data structure, serializes it into a byte
stream, and/or writes it to disk.
A collection of extensions that are released, versioned, and distributed
together. Packages may be downloaded directly from version control
repositories or in [archive files] generated by a release tag.

MUST, SHOULD, MAY, etc.
#### Source Distribution ####

: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [IETF RFC 2119].
An archive of the source code for the release of a Package, together with
metadata defined by this spec, distributed for other developers to build,
install, and use. The file name of a Source Distribution consists of the
package name, a dash, and the version, e.g., `pgtap-1.14.3.zip`.

## Data Types
#### Extension ####

Fields in the [Structure](#Structure) section describe data elements, each of
which has an associated data type as described herein. Each is based on
the primitive types defined by [JSON]: *object*, *array*, *string*, *number*,
and *boolean*.
A software component that extends the capabilities of a PostgreSQL database or
cluster. Extensions may be `CREATE EXTENSION` [extensions], [background
workers], command-line apps, [loadable modules], shared libraries, and more.

Term
: A *Term* is a *string* that **MUST** be at least two characters long, and
contain no slash (`/`), backslash (`\`), control, or space characters.
#### Consumer ####

Tag
: A *Tag* is a *string* that **MUST** be at least two and no more than 255
characters long, and contain no slash (`/`), backslash (`\`), or control
characters.
Code that reads a metadata file, deserializes it into a data structure in
memory, or interprets a data structure of metadata elements.

URI
: *URI* is a *string* containing a valid Uniform Resource Identifier or
Locator as defined by [IETF RFC 3986].
#### Producer ####

Version
: A *Version* is a *string* containing a value that describes the version
number of extensions or distributions, and adhere to the format of the
[Semantic Versioning 2.0.0 Specification][semver].
Code that constructs a metadata data structure, serializes it into a byte
stream, and/or writes it to disk.

Version Range
: A *Version Range* is a *string* that describes a range of Versions that
may be present or installed to fulfill prerequisites. It is specified in
detail in the [Version Ranges](#version-ranges) section.
### Data Types ###

License String
: A *License String* is a *string* with a restricted set of values. Valid
values are defined by the [SPDX License List v3.24.0].
Properties in the [Structure](#structure) section describe data elements, each
of which has an associated data type as described herein. Each is based on the
primitive types defined by [JSON]: *object*, *array*, *string*, *number*, and
*boolean*. Other types are subtypes of these primitives and define compound
data structures or define constraints on the values of a data element.

License Expression
: A *License Expression* is a *string* that represents one or more licenses
under which the contents of the package are distributed by combining
License Strings into a single value. The format is defined by the [SPDX
Standard License Expression].
#### Boolean ####

## Structure
A *Boolean* is used to provide a true or false value. It **MUST** be
represented as a defined (not `null`) value.

The metadata structure is an object. This section describes valid keys within
the [Map](#Map).
#### String ####

Any keys not described in this specification document (whether top-level or
within compound data structures described herein) are considered *custom keys*
and **must** begin with an "x" or "X" and be followed by an underscore; i.e.,
they must match the pattern: `/\Ax_/i`. If a custom key refers to a compound
data structure, subkeys within it do not need an "x_" or "X_" prefix.
A *String* is data element containing a non-zero length sequence of Unicode
characters.

Consumers of metadata may ignore any or all custom keys. All other keys not
described herein are invalid and should be ignored by consumers. Producers
must not generate or output invalid keys.
#### Array ####

For each key, an example is provided followed by a description. The
description begins with the version of spec in which the key was added or in
which the definition was modified, whether the key is *required* or
*optional*, and the data type of the corresponding data element. These items
are in parentheses, brackets, and braces, respectively.
An *Array* is an ordered collection of one or more data elements. Items in an
Array may be of mixed types.

If a data type is a [Map](#Map) or [Map](#Map) subtype, valid subkeys will be
described as well. All examples are represented as [JSON].
#### Object ####

<!-- Nothing deprecated yet.
An *Object* is an unordered collection of zero or more data elements
("values"), indexed by associated [String](#string) elements ("keys"). An
Object's values may be of mixed types.

Some fields are marked *Deprecated*. These are shown for historical context
and must not be produced in or consumed from any metadata structure of version
1 or higher.
#### Term ####

-->
A *Term* is a [String](#string) that **MUST** be at least two characters long,
and contain no slash (`/`), backslash (`\`), control, or space characters.

Required Fields
---------------
#### Tag ####

A *Tag* is a [String](#string) that **MUST** be at least two and no more than
255 characters long, and contain no slash (`/`), backslash (`\`), or control
characters.

#### URI ####

*URI* is a [String](#string) containing a valid Uniform Resource Identifier or
Locator as defined by [IETF RFC 3986].

#### Version ####

A *Version* is a [String](#string) containing a value that describes the
version number of extensions or distributions, and adhere to the format of the
[Semantic Versioning 2.0.0 Specification][semver].

#### Version Range ####

A *Version Range* is a [String](#string) that describes a range of Versions
that may be present or installed to fulfill prerequisites. It is specified in
detail in the [Version Ranges](#version-ranges) section.

#### License String ####

A *License String* is a [String](#string) with a restricted set of values.
Valid values are defined by the [SPDX License List v3.24.0].

#### License Expression ####

A *License Expression* is a [String](#string) that represents one or more
licenses under which the contents of the package are distributed by combining
License Strings into a single value. The format is defined by the [SPDX
Standard License Expression].

## Structure

The metadata structure is an [Object](#object). This section describes valid
properties of the [Object](#object).

Any properties not described in this specification document (whether top-level
or within compound data structures described herein) are considered *custom
properties* and **MUST** begin with an "x" or "X" and be followed by an
underscore; i.e., they must match the regular expression pattern `^[xX]_.`. If
a custom property refers to a compound data structure, properties within it do
not need an "x_" or "X_" prefix.

[Consumers](#consumer) of metadata may ignore any or all custom properties.
All other properties not described herein are invalid and should be ignored by
[Consumers](#consumer). [Producers](#producer) must not generate or output
invalid properties.

For each property, an example is provided followed by a description. The
description begins with the version of spec in which the property was added or
in which the definition was modified, whether the property is *required* or
*optional*, and the data type of the corresponding value. These items are in
parentheses, brackets, and braces, respectively.

If a data type is an [Object](#object), valid sub-properties will be described
as well. All examples are represented as [JSON].

Some properties are marked *Deprecated*. These are shown for historical
context and must not be produced in or consumed from any metadata structure of
version 2 or higher.

### Required Properties

### abstract ###
#### abstract ####

Example:

``` json
"abstract": "Unit testing for PostgreSQL"
```

(Spec 1) [required] {[String](#String)}
(Spec 1) [required] {[String](#string)}

This is a short description of the purpose of the distribution.

Expand Down Expand Up @@ -320,7 +352,7 @@ subkeys:
* **version**: This field contains a [Version](#Version) for the extension.
All extensions must have versions. Required.

* **abstract**: A short [String](#String) value describing the extension.
* **abstract**: A short [String](#string) value describing the extension.
Optional.

* **docfile**: The value must contain a relative file path from the root of
Expand Down Expand Up @@ -393,7 +425,7 @@ Example:
"description": "pgTAP is a suite of database functions that make it easy to write TAP-emitting unit tests in psql scripts or xUnit-style test functions."
```

(Spec 1) [optional] {[String](#String)}
(Spec 1) [optional] {[String](#string)}

A longer, more complete description of the purpose or intended use of the
distribution than the one provided by the `abstract` key.
Expand All @@ -406,7 +438,7 @@ Example:
"generated_by": "Module::Build::PGXN version 0.42"
```

(Spec 1) [optional] {[String](#String)}
(Spec 1) [optional] {[String](#string)}

This field indicates the tool that was used to create this metadata. There are
no defined semantics for this field, but it is traditional to use a string in
Expand Down Expand Up @@ -502,7 +534,7 @@ Example:
"release_status": "stable"
```

(Spec 1) [optional] {[String](#String)}
(Spec 1) [optional] {[String](#string)}

This field specifies the release status of this distribution. It **must** have
one of the following values:
Expand Down Expand Up @@ -782,7 +814,7 @@ Sims, David Golden, and Ricardo Signes. Ported to PGXN by David E. Wheeler.
[source code repository]: https://www.rfc-editor.org/info/rfc9591
[PostgreSQL License]: https://www.postgresql.org/about/licence/
[CC BY-SA 4.0]: https://creativecommons.org/licenses/by-sa/4.0/ "Attribution-Sharealike 4.0 International"
[MultiMarkdown]: https://fletcherpenney.net/multimarkdown/
[Github Flavored Markdown]: https://github.github.com/gfm/
[Markdown]: https://daringfireball.net/projects/markdown/
[master.pgxn.org/meta/spec.txt]: https://master.pgxn.org/meta/spec.txt
[pgxn.org/spec/]: https://pgxn.org/spec/
Expand Down

0 comments on commit 7035d0d

Please sign in to comment.