Skip to content

Enhance lifecycle.md with abstract and version info #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
miqui wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Enhance lifecycle.md with abstract and version info #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 72 additions & 32 deletions src/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,21 @@
# Lifecycle Specification

## Version History
## Abstract

@handrews handrews Aug 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The abstract gets added by the build system, and its text is in spec.config.json. I have no idea why, but I assume this is a ReSpec thing.


| Version | Date | Notes |
| ---- | ---- | ---- |
| 1.0.0 | TBD | Initial release |
TODO: One or two sentences summarizing what the Lifecycle Object is and the
problem it solves.

## Version 1.0.0

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14)
[RFC2119](https://tools.ietf.org/html/rfc2119)
[RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they
appear in all capitals, as shown here.

TODO: Confirm license. OAI companion specifications typically use the
[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).

## Introduction

Expand All @@ -21,50 +32,79 @@ features:
# Lifecycle Object fields here
```

Compatibility between versions of this specification and versions of the OpenAPI
Specification is determined by publication date. The rules for determining
compatible version pairs are documented in [TODO: link or section].
Compatibility between versions of this specification and versions of the
OpenAPI Specification is determined by publication date. The rules for
determining compatible version pairs are documented under
[Compatibility](#compatibility).

## Definitions

### Lifecycle Object
### Lifecycle

A **Lifecycle Object** is ...

#### Fixed Fields

| Field Name | Type | Description |
| ---- | ---- | ---- |
| TODO | TODO | TODO |
TODO: A short, informal description of what a Lifecycle is conceptually —
not the field-by-field schema. The Fixed Fields for the Lifecycle Object
live under [Schema](#schema) below.

### Schema Object

Comment on lines 40 to 49

@handrews handrews Aug 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have this section in the OAS (or at least not anymore), so I went looking at Arazzo. I think based on how Arazzo uses it, defining "Lifecycle" in general terms here makes sense, but not "Schema Object".

@miqui miqui Aug 19, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, thanks for the feedback.

A **Schema Object** is a JSON Schema schema as defined by the OpenAPI Specification
in use. Within this document, Schema Objects behave according to the OAS dialect
in effect in the containing OpenAPI document.
A **Schema Object** is a JSON Schema schema as defined by the OpenAPI
Specification in use. Within this document, Schema Objects behave according
to the OAS dialect in effect in the containing OpenAPI document.

## Specification

### Version `1.0`
### Versions

This document is the Lifecycle Specification version 1.0.0.
The Lifecycle Specification is versioned using a `major`.`minor`.`patch`
scheme. The `major`.`minor` portion of the version string (for example,
`1.0`) designates the Lifecycle feature set in effect. `patch` releases
address errors in, or provide clarifications to, this document without
changing the feature set; tooling SHOULD treat all patch releases within a
`major`.`minor` line as equivalent.
Comment on lines +56 to +63

@handrews handrews Aug 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given the ongoing debate about the patch number, let's do the version stuff in its own PR so that people can debate that separately.


### Notation
#### Compatibility

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 [RFC2119](https://tools.ietf.org/html/rfc2119).
TODO: Document the rules for determining which versions of this
specification are compatible with which versions of the OpenAPI
Specification (referenced from
[Relationship to the OpenAPI Specification](#relationship-to-the-openapi-specification)
above).

### Schema

@handrews handrews Aug 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've changed this to Specification in the other documents.


Implementations that validate Lifecycle Objects MUST use the schema published at
`https://spec.openapis.org/lifecycle/1.0/schema/WORK-IN-PROGRESS`.
In the following description, if a field is not explicitly **REQUIRED** or
described with a MUST or SHALL, it can be considered OPTIONAL.

When validating a Lifecycle Object within an OpenAPI document, the Schema Object
schema in effect is determined by the OAS dialect declared in that document.
Standalone validation of Lifecycle Objects uses the standard JSON Schema
2020-12 dialect for Schema Object positions.
#### Lifecycle Object

## Appendix A — Revision History
A **Lifecycle Object** is ...

TODO: Document notable changes between versions.
##### Fixed Fields

| Field Name | Type | Description |
| ---- | ---- | ---- |
| TODO | TODO | TODO |

This object MAY be extended with [Specification Extensions](#specification-extensions).

Implementations that validate Lifecycle Objects MUST use the schema
published at `https://spec.openapis.org/lifecycle/1.0/schema/WORK-IN-PROGRESS`.
When validating a Lifecycle Object within an OpenAPI document, the Schema
Object schema in effect is determined by the OAS dialect declared in that
document. Standalone validation of Lifecycle Objects uses the standard JSON
Schema 2020-12 dialect for Schema Object positions.

TODO: Replace `WORK-IN-PROGRESS` with a dated schema identifier before
publication (e.g. `2026-MM-DD`), matching OAI hosting convention.

### Specification Extensions

TODO: Decide whether `x-` prefixed extension fields are permitted on the
Lifecycle Object, and document the pattern (field name pattern, reserved
prefixes, allowed value types) if so.

## Appendix A: Revision History

| Version | Date | Notes |
| ---- | ---- | ---- |
| 1.0.0 | TBD | Initial release |