From 2b94b0776ddb06bd0c8f9a640bc273631d224659 Mon Sep 17 00:00:00 2001 From: "David E. Wheeler" Date: Fri, 5 Jul 2024 15:35:11 -0400 Subject: [PATCH] Use headers instead of definition lists And add descriptions of the JSON types --- spec.md | 218 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 125 insertions(+), 93 deletions(-) diff --git a/spec.md b/spec.md index d1bd65e..a290198 100644 --- a/spec.md +++ b/spec.md @@ -10,7 +10,7 @@ # 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 @@ -18,22 +18,21 @@ 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. @@ -43,7 +42,7 @@ 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 @@ -51,112 +50,145 @@ 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 #### - +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: @@ -164,7 +196,7 @@ Example: "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. @@ -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 @@ -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. @@ -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 @@ -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: @@ -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/