Skip to content

Commit

Permalink
Start revising spec for v2
Browse files Browse the repository at this point in the history
  • Loading branch information
@theory
theory committed Jul 3, 2024
1 parent a9d3421 commit a69c30f
Showing 1 changed file with 101 additions and 180 deletions.
281 changes: 101 additions & 180 deletions spec.md
View file
Original file line number Diff line number Diff line change
@@ -1,216 +1,130 @@
Name
====
* **Source:** PostgreSQL Extension Network
* **RFC**: TBD
* **Version**: 2.0.0-draft1
* **Status**: Draft
* **Category**: Standards Track
* **Published**: TBD
* **Authors**:
* David E. Wheeler, PGXN, Tembo

PGXN Meta Spec - The PGXN distribution metadata specification
# RFC TBD
# PostgreSQL Extension Network Distribution Metadata Specification

Version
=======
## Abstract

1.0.2
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.

Synopsis
========
## Status of This Memo

``` json
{
"name": "pgTAP",
"abstract": "Unit testing for PostgreSQL",
"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.",
"version": "0.26.0",
"maintainer": [
"David E. Wheeler <theory@pgxn.org>",
"pgTAP List <pgtap-users@googlegroups.com>"
],
"license": {
"PostgreSQL": "https://www.postgresql.org/about/licence"
},
"prereqs": {
"runtime": {
"requires": {
"plpgsql": 0,
"PostgreSQL": "8.0.0"
},
"recommends": {
"PostgreSQL": "8.4.0"
}
}
},
"provides": {
"pgtap": {
"file": "sql/pgtap.sql",
"docfile": "doc/pgtap.mmd",
"version": "0.2.4",
"abstract": "Unit testing assertions for PostgreSQL"
},
"schematap": {
"file": "sql/schematap.sql",
"docfile": "doc/schematap.mmd",
"version": "0.2.4",
"abstract": "Schema testing assertions for PostgreSQL"
}
},
"resources": {
"homepage": "https://pgtap.org/",
"bugtracker": {
"web": "https://github.com/theory/pgtap/issues"
},
"repository": {
"url": "https://github.com/theory/pgtap.git",
"web": "https://github.com/theory/pgtap",
"type": "git"
}
},
"generated_by": "David E. Wheeler",
"meta-spec": {
"version": "1.0.0",
"url": "https://pgxn.org/meta/spec.txt"
},
"tags": [
"testing",
"unit testing",
"tap",
"tddd",
"test driven database development"
]
}
```
This is an Internet Standards Track document.

Description
===========

This document describes version 1.0.0 of the PGXN distribution metadata
specification, also known as the "PGXN Meta Spec." It is formatted using the
[MultiMarkdown] 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.

This document is stable. Any revisions to this specification for typo
corrections and prose clarifications may be issued as "PGXN Meta Spec
1.0.*x*". These revisions will never change semantics or add or remove
specified behavior.

Distribution metadata describe important properties of PGXN distributions.
Distribution building tools 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 distributions.

Terminology
===========

distribution
: The primary object described by the metadata. In the context of this
document it usually refers to a collection of extensions, source code,
utilities, tests, and/or documents that are distributed together for other
developers to use. Examples of distributions are [`semver`], [`pair`], and
[`pgTAP`].

extension
: A reusable library of code contained in a single file or within files
referenced by the [`CREATE EXTENSION` statement]. Extensions usually
contain one or more PostgreSQL objects --- such as data types, functions,
and operators --- and are often referred to by the name of a primary
object that can be mapped to the file name. For example, one might refer
to `pgTAP` instead of `sql/pgtap.sql`.

consumer
: Code that reads a metadata file, deserializes it into a data structure in
memory, or interprets a data structure of metadata elements.
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
[master.pgxn.org/meta/spec.txt]. A generated HTML-formatted copy found at
[pgxn.org/spec/] may also be considered canonical.

producer
: Code that constructs a metadata data structure, serializes into a byte
stream and/or writes it to disk.
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].

must, should, may, etc.
: These terms are interpreted as described in [IETF RFC 2119].

Data Types
==========
## Copyright Notice

Fields in the [Structure](#Structure) section describe data elements, each of
which has an associated data type as described herein. There are four
primitive types: *Boolean*, *String*, *List*, and *Map*. Other types are
subtypes of primitives and define compound data structures or define
constraints on the values of a data element.
Copyright (c) 2010-2024 PGXN and the persons identified as the document
authors. All rights reserved.

Boolean
-------
This RFC is distributed under the [CC BY-SA 4.0] license.

A *Boolean* is used to provide a true or false value. It **must** be
represented as a defined (not `null`) value.
Code Components extracted from this document MUST include the [PostgreSQL
License].

String
------
## Introduction

A *String* is data element containing a non-zero length sequence of Unicode
characters.
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.

List
----
### Terminology

A *List* is an ordered collection of zero or more data elements. Elements of a
List may be of mixed types.
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`].

Producers **must** represent List elements using a data structure which
unambiguously indicates that multiple values are possible, such as a
JavaScript array.
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.

Consumers expecting a List **must** consider a [String](#String) as equivalent
to a List of length 1.
Consumer
: Code that reads a metadata file, deserializes it into a data structure in
memory, or interprets a data structure of metadata elements.

Map
---
Producer
: Code that constructs a metadata data structure, serializes it into a byte
stream, and/or writes it to disk.

A *Map* is an unordered collection of zero or more data elements ("values"),
indexed by associated [String](#String) elements ("keys"). The Map’s value
elements may be of mixed types.
MUST, SHOULD, MAY, etc.

License String
--------------
: 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].

A *License String* is a subtype of [String](#String) with a restricted set of
values. Valid values are described in detail in the description of the
[license field](#license).
## Data Types

Term
----
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 *Term* is a subtype of [String](#String) that **must** be at least two
characters long contain no slash (`/`), backslash (`\`), control, or space
characters.
Term
: A *Term* is a *string* that **MUST** be at least two characters long, and
contain no slash (`/`), backslash (`\`), control, or space characters.

Tag
---

A *Tag* is a subtype of [String](#String) that **must** be fewer than 256
characters long contain no slash (`/`), backslash (`\`), or control
characters.
: 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.

URI
---

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

Version
-------

A *Version* is a subtype of [String](#String) containing a value that
describes the version number of extensions or distributions. Restrictions on
format are described in detail in the [Version Format](#Version.Format)
section.
: 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].

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.

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].

The *Version Range* type is a subtype of [String](#String). It 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 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].

Structure
=========
## Structure

The metadata structure is a data element of type [Map](#Map). This section
describes valid keys within the [Map](#Map).
The metadata structure is an object. This section describes valid keys within
the [Map](#Map).

Any keys not described in this specification document (whether top-level or
within compound data structures described herein) are considered *custom keys*
Expand Down Expand Up @@ -865,16 +779,23 @@ The PGXN Meta Spec borrows heavily from the [CPAN Meta Spec], which was
originally written by Ken Williams in 2003 and has since been updated by Randy
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/
[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/
[`semver`]: https://pgxn.org/dist/semver/
[`pair`]: https://pgxn.org/dist/pair/
[`pgTAP`]: https://pgxn.org/dist/pgtap/
[`vector`]: https://pgxn.org/dist/vector/
[`citus`]: https://pgxn.org/dist/citus/
[`CREATE EXTENSION` statement]: https://www.postgresql.org/docs/current/static/sql-createextension.html
[IETF RFC 2119]: https://www.ietf.org/rfc/rfc2119.txt
[JSON]: https://json.org/
[IETF RFC 3986]: https://www.rfc-editor.org/info/rfc3986
"RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"
[semver]: https://semver.org/
[SPDX License List v3.24.0]: https://github.com/spdx/license-list-data/tree/v3.24.0
[SPDX Standard License Expression]: https://spdx.github.io/spdx-spec/v3.0/annexes/SPDX-license-expressions/
[CPAN Meta Spec]: https://metacpan.org/pod/CPAN::Meta::Spec
[PGXN]: https://pgxn.org/

0 comments on commit a69c30f

Please sign in to comment.