Skip to content

Commit a69c30f

Browse files
theorytheory
committed
Start revising spec for v2
1 parent a9d3421 commit a69c30f

File tree

1 file changed

+101
-180
lines changed

1 file changed

+101
-180
lines changed

‎spec.md

Lines changed: 101 additions & 180 deletions
Original file line numberDiff line numberDiff line change
@@ -1,216 +1,130 @@
1-
Name
2-
====
1+
* **Source:** PostgreSQL Extension Network
2+
* **RFC**: TBD
3+
* **Version**: 2.0.0-draft1
4+
* **Status**: Draft
5+
* **Category**: Standards Track
6+
* **Published**: TBD
7+
* **Authors**:
8+
* David E. Wheeler, PGXN, Tembo
39

4-
PGXN Meta Spec - The PGXN distribution metadata specification
10+
# RFC TBD
11+
# PostgreSQL Extension Network Distribution Metadata Specification
512

6-
Version
7-
=======
13+
## Abstract
814

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

11-
Synopsis
12-
========
21+
## Status of This Memo
1322

14-
``` json
15-
{
16-
"name": "pgTAP",
17-
"abstract": "Unit testing for PostgreSQL",
18-
"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.",
19-
"version": "0.26.0",
20-
"maintainer": [
21-
"David E. Wheeler <[email protected]>",
22-
"pgTAP List <[email protected]>"
23-
],
24-
"license": {
25-
"PostgreSQL": "https://www.postgresql.org/about/licence"
26-
},
27-
"prereqs": {
28-
"runtime": {
29-
"requires": {
30-
"plpgsql": 0,
31-
"PostgreSQL": "8.0.0"
32-
},
33-
"recommends": {
34-
"PostgreSQL": "8.4.0"
35-
}
36-
}
37-
},
38-
"provides": {
39-
"pgtap": {
40-
"file": "sql/pgtap.sql",
41-
"docfile": "doc/pgtap.mmd",
42-
"version": "0.2.4",
43-
"abstract": "Unit testing assertions for PostgreSQL"
44-
},
45-
"schematap": {
46-
"file": "sql/schematap.sql",
47-
"docfile": "doc/schematap.mmd",
48-
"version": "0.2.4",
49-
"abstract": "Schema testing assertions for PostgreSQL"
50-
}
51-
},
52-
"resources": {
53-
"homepage": "https://pgtap.org/",
54-
"bugtracker": {
55-
"web": "https://github.com/theory/pgtap/issues"
56-
},
57-
"repository": {
58-
"url": "https://github.com/theory/pgtap.git",
59-
"web": "https://github.com/theory/pgtap",
60-
"type": "git"
61-
}
62-
},
63-
"generated_by": "David E. Wheeler",
64-
"meta-spec": {
65-
"version": "1.0.0",
66-
"url": "https://pgxn.org/meta/spec.txt"
67-
},
68-
"tags": [
69-
"testing",
70-
"unit testing",
71-
"tap",
72-
"tddd",
73-
"test driven database development"
74-
]
75-
}
76-
```
23+
This is an Internet Standards Track document.
7724

78-
Description
79-
===========
80-
81-
This document describes version 1.0.0 of the PGXN distribution metadata
82-
specification, also known as the "PGXN Meta Spec." It is formatted using the
83-
[MultiMarkdown] variant of [Markdown], and the canonical copy may always be
84-
found at [master.pgxn.org/meta/spec.txt]. A generated HTML-formatted copy
85-
found at [pgxn.org/spec/] may also be considered canonical.
86-
87-
This document is stable. Any revisions to this specification for typo
88-
corrections and prose clarifications may be issued as "PGXN Meta Spec
89-
1.0.*x*". These revisions will never change semantics or add or remove
90-
specified behavior.
91-
92-
Distribution metadata describe important properties of PGXN distributions.
93-
Distribution building tools should create a metadata file in accordance
94-
with this specification and include it with the distribution for use by
95-
automated tools that index, examine, package, or install PGXN distributions.
96-
97-
Terminology
98-
===========
99-
100-
distribution
101-
: The primary object described by the metadata. In the context of this
102-
document it usually refers to a collection of extensions, source code,
103-
utilities, tests, and/or documents that are distributed together for other
104-
developers to use. Examples of distributions are [`semver`], [`pair`], and
105-
[`pgTAP`].
106-
107-
extension
108-
: A reusable library of code contained in a single file or within files
109-
referenced by the [`CREATE EXTENSION` statement]. Extensions usually
110-
contain one or more PostgreSQL objects --- such as data types, functions,
111-
and operators --- and are often referred to by the name of a primary
112-
object that can be mapped to the file name. For example, one might refer
113-
to `pgTAP` instead of `sql/pgtap.sql`.
114-
115-
consumer
116-
: Code that reads a metadata file, deserializes it into a data structure in
117-
memory, or interprets a data structure of metadata elements.
25+
This RFC represents the consensus of the distributed community of PostgreSQL
26+
extension developes, distributors, and packagers, generally referred to as the
27+
"PostgreSQL Extension Ecosystem". It is formatted using the [MultiMarkdown]
28+
variant of [Markdown], and the canonical copy may always be found at
29+
[master.pgxn.org/meta/spec.txt]. A generated HTML-formatted copy found at
30+
[pgxn.org/spec/] may also be considered canonical.
11831

119-
producer
120-
: Code that constructs a metadata data structure, serializes into a byte
121-
stream and/or writes it to disk.
32+
Information about the current status of this document, any errata, and how to
33+
provide feedback on it may be obtained from its [source code repository].
12234

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

126-
Data Types
127-
==========
36+
## Copyright Notice
12837

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

135-
Boolean
136-
-------
41+
This RFC is distributed under the [CC BY-SA 4.0] license.
13742

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

141-
String
142-
------
46+
## Introduction
14347

144-
A *String* is data element containing a non-zero length sequence of Unicode
145-
characters.
48+
Distribution metadata describe important properties of PGXN source code
49+
distributions. Tools that build PGXN source distribution archives should
50+
create a metadata file in accordance with this specification and include it
51+
with the distribution for use by automated tools that index, examine, package,
52+
or install PGXN source distributions.
14653

147-
List
148-
----
54+
### Terminology
14955

150-
A *List* is an ordered collection of zero or more data elements. Elements of a
151-
List may be of mixed types.
56+
Source Code Package
57+
: The primary object described by the metadata, also referred to as "source
58+
package" and sometimes just "package". In the context of this document the
59+
term refers to a collection of extensions, source code, utilities, tests,
60+
and/or documents that are distributed together for other developers to
61+
build, install, and use. Examples of source packages include [`semver`],
62+
[`vector`], and [`citus`].
15263

153-
Producers **must** represent List elements using a data structure which
154-
unambiguously indicates that multiple values are possible, such as a
155-
JavaScript array.
64+
Extension
65+
: A software component that extends the capabilities of a PostgreSQL
66+
database or cluster. Extensions may be `CREATE EXTENSION` [extensions],
67+
[background workers], command-line apps, [loadable modules], shared
68+
libraries, and more.
15669

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

160-
Map
161-
---
74+
Producer
75+
: Code that constructs a metadata data structure, serializes it into a byte
76+
stream, and/or writes it to disk.
16277

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

167-
License String
168-
--------------
80+
: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
81+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
82+
document are to be interpreted as described in [IETF RFC 2119].
16983

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

174-
Term
175-
----
86+
Fields in the [Structure](#Structure) section describe data elements, each of
87+
which has an associated data type as described herein. Each is based on
88+
the primitive types defined by [JSON]: *object*, *array*, *string*, *number*,
89+
and *boolean*.
17690

177-
A *Term* is a subtype of [String](#String) that **must** be at least two
178-
characters long contain no slash (`/`), backslash (`\`), control, or space
179-
characters.
91+
Term
92+
: A *Term* is a *string* that **MUST** be at least two characters long, and
93+
contain no slash (`/`), backslash (`\`), control, or space characters.
18094

18195
Tag
182-
---
183-
184-
A *Tag* is a subtype of [String](#String) that **must** be fewer than 256
185-
characters long contain no slash (`/`), backslash (`\`), or control
186-
characters.
96+
: A *Tag* is a *string* that **MUST** be at least two and no more than 255
97+
characters long, and contain no slash (`/`), backslash (`\`), or control
98+
characters.
18799

188100
URI
189-
---
190-
191-
*URI* is a subtype of [String](#String) containing a Uniform Resource
192-
Identifier or Locator.
101+
: *URI* is a *string* containing a valid Uniform Resource Identifier or
102+
Locator as defined by [IETF RFC 3986].
193103

194104
Version
195-
-------
196-
197-
A *Version* is a subtype of [String](#String) containing a value that
198-
describes the version number of extensions or distributions. Restrictions on
199-
format are described in detail in the [Version Format](#Version.Format)
200-
section.
105+
: A *Version* is a *string* containing a value that describes the version
106+
number of extensions or distributions, and adhere to the format of the
107+
[Semantic Versioning 2.0.0 Specification][semver].
201108

202109
Version Range
203-
-------------
110+
: A *Version Range* is a *string* that describes a range of Versions that
111+
may be present or installed to fulfill prerequisites. It is specified in
112+
detail in the [Version Ranges](#version-ranges) section.
113+
114+
License String
115+
: A *License String* is a *string* with a restricted set of values. Valid
116+
values are defined by the [SPDX License List v3.24.0].
204117

205-
The *Version Range* type is a subtype of [String](#String). It describes a
206-
range of Versions that may be present or installed to fulfill prerequisites.
207-
It is specified in detail in the [Version Ranges](#Version.Ranges) section.
118+
License Expression
119+
: A *License Expression* is a *string* that represents one or more licenses
120+
under which the contents of the package are distributed by combining
121+
License Strings into a single value. The format is defined by the [SPDX
122+
Standard License Expression].
208123

209-
Structure
210-
=========
124+
## Structure
211125

212-
The metadata structure is a data element of type [Map](#Map). This section
213-
describes valid keys within the [Map](#Map).
126+
The metadata structure is an object. This section describes valid keys within
127+
the [Map](#Map).
214128

215129
Any keys not described in this specification document (whether top-level or
216130
within compound data structures described herein) are considered *custom keys*
@@ -865,16 +779,23 @@ The PGXN Meta Spec borrows heavily from the [CPAN Meta Spec], which was
865779
originally written by Ken Williams in 2003 and has since been updated by Randy
866780
Sims, David Golden, and Ricardo Signes. Ported to PGXN by David E. Wheeler.
867781

782+
[source code repository]: https://www.rfc-editor.org/info/rfc9591
783+
[PostgreSQL License]: https://www.postgresql.org/about/licence/
784+
[CC BY-SA 4.0]: https://creativecommons.org/licenses/by-sa/4.0/ "Attribution-Sharealike 4.0 International"
868785
[MultiMarkdown]: https://fletcherpenney.net/multimarkdown/
869786
[Markdown]: https://daringfireball.net/projects/markdown/
870787
[master.pgxn.org/meta/spec.txt]: https://master.pgxn.org/meta/spec.txt
871788
[pgxn.org/spec/]: https://pgxn.org/spec/
872789
[`semver`]: https://pgxn.org/dist/semver/
873-
[`pair`]: https://pgxn.org/dist/pair/
874-
[`pgTAP`]: https://pgxn.org/dist/pgtap/
790+
[`vector`]: https://pgxn.org/dist/vector/
791+
[`citus`]: https://pgxn.org/dist/citus/
875792
[`CREATE EXTENSION` statement]: https://www.postgresql.org/docs/current/static/sql-createextension.html
876793
[IETF RFC 2119]: https://www.ietf.org/rfc/rfc2119.txt
877794
[JSON]: https://json.org/
795+
[IETF RFC 3986]: https://www.rfc-editor.org/info/rfc3986
796+
"RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"
878797
[semver]: https://semver.org/
798+
[SPDX License List v3.24.0]: https://github.com/spdx/license-list-data/tree/v3.24.0
799+
[SPDX Standard License Expression]: https://spdx.github.io/spdx-spec/v3.0/annexes/SPDX-license-expressions/
879800
[CPAN Meta Spec]: https://metacpan.org/pod/CPAN::Meta::Spec
880801
[PGXN]: https://pgxn.org/

0 commit comments

Comments
 (0)