Skip to content
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

Jump to bottom

Add an intro and other missing sections #47

Merged
merged 9 commits into from
Sep 13, 2024
Merged

Add an intro and other missing sections #47

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d5ddeca
Add an intro, a note about versions, and remove the data types sectio…
lornajane Sep 1, 2024
9e2dcb6
Apply suggestions from code review
lornajane Sep 8, 2024
ffa3377
Better OpenAPI wording in the intro
lornajane Sep 8, 2024
1aeaa20
Improve Overlay definition and intro, with supervision
lornajane Sep 10, 2024
fc517a0
Update versions/1.0.0.md
lornajane Sep 10, 2024
ad2430d
Merge remote-tracking branch 'upstream/main' into pr/47
ralfhandl Sep 10, 2024
665a0fb
Update 1.0.0.md
ralfhandl Sep 10, 2024
09700c3
Fix links
ralfhandl Sep 10, 2024
dec193f
respec-style reference
ralfhandl Sep 10, 2024
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
22 changes: 13 additions & 9 deletions versions/1.0.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,27 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap

## Introduction

TBD
The Overlay Specification is an extension or companion to the [[OpenAPI]] specification.
An Overlay describes a set of changes to be applied or "overlaid" onto an existing OpenAPI description.
lornajane marked this conversation as resolved.
Show resolved Hide resolved
Comment on lines +11 to +12
Copy link
Contributor

Choose a reason for hiding this comment

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

Do we want to restrict Overlays to only operate on OpenAPI documents? For the most part the spec could easily be applied to any JSON or YAML doc. And in several places we seem to allow base documents of other types, e.g. target is described as

URL to the target document (such as an [[OpenAPI]] document) ...

Copy link
Contributor

Choose a reason for hiding this comment

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

The repo README.md says

The Overlay specification defines a way of creating documents that contain information to be merged with an OpenAPI description at some later point in time, for the purpose of updating the OpenAPI description with additional information.

Given that with RFC6902 and RFC7386 there are already two document formats for modifying arbitrary JSON documents, I'd keep to the original scope.

@kevinswiber @lornajane?

Copy link
Contributor

@ralfhandl ralfhandl Sep 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

@mikekistler How about merging this PR and continuing the discussion in


The main purpose of the Overlay Specification is to provide a way to repeatably apply transformations to one or many OpenAPI descriptions.
Use cases include updating descriptions, adding metadata to be consumed by another tool, or removing certain elements from an API description before sharing it with partners.
An Overlay may be specific to a single OpenAPI description, or be designed to apply the same transform to any OpenAPI description.

## Definitions

### Overlay Document
### Overlay

An overlay document contains an ordered list of [Action Objects](#overlay-actions) that are to be applied to the target document. Each [Action Object](#action-object) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [[RFC9535|JSONPath]] query expression that identifies the elements of the target document to be updated and the modifier determines the change.
An Overlay is a JSON or YAML structure containing an ordered list of [Action Objects](#overlay-actions) that are to be applied to the target document. Each [Action Object](#action-object) has a `target` property and a modifier type (`update` or `remove`). The `target` property is a [[RFC9535|JSONPath]] query expression that identifies the elements of the target document to be updated and the modifier determines the change.

## Specification

### Versions

TBD
The Overlay Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example 1.0) SHALL designate the Overlay feature set. `.patch` versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example.

**Note:** Version 1.0.0 of the Overlay Specification is being released after spending some time in draft, and after being adopted by tool providers.
Check with your tool provider for the details of what is supported in each tool.

### Format

Expand All @@ -38,10 +46,6 @@ In order to preserve the ability to round-trip between YAML and JSON formats, [[

It is RECOMMENDED that the root Overlay document be named: `overlay.json` or `overlay.yaml`.

### Data Types

TBD

### Relative References in URLs

Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
Expand All @@ -53,7 +57,7 @@ In the following description, if a field is not explicitly **REQUIRED** or descr

#### Overlay Object

This is the root object of the [Overlay document](#overlay-document).
This is the root object of the [Overlay](#overlay).

##### Fixed Fields

Expand Down