moved reusable definitions under a single element #633

fehguy · 2016-04-08T13:06:34Z

Fixes #563

fehguy · 2016-04-08T16:35:54Z

versions/3.0.md

 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API.
-<a name="oasDefinitions"></a>definitions | [Definitions Object](#definitionsObject) | An object to hold data types produced and consumed by operations.
+<a name="oasSchemas"></a>schemas | [Schemas Object](#schemasObject) | An element to hold various schemas for the specification.


global
library
definitions (swap)?
@OAI/tdc please provide any other naming suggestions

As mentioned in #563, I would prefer definitions/schemas to schemas/definitions, though I can understand resistance to reusing a property name from a previous version with a different name.

For machine readers, the distinction should be clear from the version property, but humans might be confused. On the other hand, schemas on the top level might lead to confusion with JSON schema (i.e. that everything in it is a JSON schema document), which only applies to the model definitions, while actually everything in here is a definition of some kind, so definitions actually captures it better.

global might be read to indicate that the contents (specifically parameters) are valid for every operation.

library doesn't cause confusion (I think), but also doesn't really say what it is.

Unfortunately I have no other ideas here.

More naming suggestions:
components
fragments
chunks

While I like definitions because that's just what they are, components work well because we commonly use the term Reusable Components as parts that can be referenced from different locations in the spec.

Another option would be declarations.

I agree with @webron that definitions is a good word, but then again, it has some baggage from 2.0. Either declarations or components works for me.

fehguy · 2016-04-08T16:36:52Z

This feature allows us to have top-level attributes which propagate down to all operations, and a separate section for (definitions) in a single block.

Also ensure that it's clarified what the override process is for the global parameters.

webron · 2016-04-11T00:09:27Z

versions/3.0.md

 <a name="oasParameters"></a>parameters | [Parameters Definitions Object](#parametersDefinitionsObject) | An object to hold parameters that can be used across operations. This property *does not* define global parameters for all operations.
 <a name="oasResponses"></a>responses | [Responses Definitions Object](#responsesDefinitionsObject) | An object to hold responses that can be used across operations. This property *does not* define global responses for all operations.
 <a name="oasSecurityDefinitions"></a>securityDefinitions | [Security Definitions Object](#securityDefinitionsObject) | Security scheme definitions that can be used across the specification.
-<a name="oasSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition.
+<a name="oasSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition.~~


The strikethrough should end at securityDefinitions. security is global to the spec and is meant to stay as-is. Also, strikethrough doesn't work well in tables. Look for my summarizing comment on this PR.

webron · 2016-04-11T00:14:55Z

I find this PR to be partial and not cover what's suggested in #563 mostly because it doesn't cover the suggested global definitions.

@fehguy - since this is your PR, would you be okay with me pushing the additional changes to the branch so those can be reviewed as part of this PR?

fehguy · 2016-04-11T21:41:24Z

@webron yep, please go for it.

IvanGoncharov · 2016-04-11T21:47:51Z

@fehguy @webron Please consider #647 as an alternative. It solve the same problem with global parameters but also allow same functionality for a group of resources. As nice bonus it's backward compatible and JSON pointers stay nice and short #/parameters/<name> instead of #/schemas/parameters/<name>.

jharmn · 2016-04-13T03:41:01Z

RAML refers to this concept as traits (http://raml.org/developers/raml-200-tutorial#resource-types).
Also, the missing aspect in this PR is how to specify that a given path uses one of these schema (really misleading name). Defining the common/reusable aspects of a given path is only useful if we can apply it.

I think this is what @ePaul is trying to accomplish in his competing PR. It seems like the right answer is somewhere between the two.

ePaul · 2016-04-13T09:29:05Z

@jasonh-n-austin Maybe I'm misunderstanding you, but I think your comment does not really apply to this PR – this is just collecting all the reusable definitions (of parameters, model schemas, ...) into one object instead of having them directly in the root object.

This is not competing with #650 (#650 is just depending on this one for implementation details).

earth2marsh · 2016-04-14T05:25:13Z

I'm 👍 for centralizing, but finding the right name is the tricky bit. components or declarations as mentioned in the line comments seem reasonable.

jharmn · 2016-04-14T13:28:24Z

@ePaul OK that's what I want to make sure we have it clearly stated, thanks. I guess we'll have to make another pass at making these usable a la traits.

fehguy · 2016-04-15T16:08:41Z

leading names: declarations, components

ePaul · 2016-04-20T20:13:30Z

versions/3.0.md

+<a name="responsesDefinitionsObject"></a> | Responses Definitions Object | Reusable responses objects.
+<a name="parametersDefinitionsObject"></a> | [Parameters Definitions Object](#parametersDefinitionsObject) | An object to hold parameters to be reused across operations. Parameter definitions can be referenced to the ones defined here.
+<a name="responseHeadersDefinitionsObject"></a> | [Response Headers Definitions Object](#responseHeadersDefinitionsObject) | Response headers to reuse across the specification.
+<a name="securityDefinitionsObject"></a> | [Security Definitions Object](#securityDefinitionsObject) | Security definitions to reuse across the specification.


Here is still something missing – in the first column we need the actual field names of this components object (like definitions, responses, parameters, ...), and different name attributes (they currently are the same as for the objects linked in the second column, which will break stuff). I guess something like componentsDefinitions, componentsResponses, ... would do for the names.

I only noted this after the merge (trying to rebase my #650), sorry.

…rom OAI#633. Also, rename it to "Interfaces Definitions Object".

moved reusable definitions under a single element [Manually ported merge] Co-authored-by: Tony Tam <[email protected]>

moved reusable definitions under a single element

e7e3e9b

fehguy added the OpenAPI.Next Proposal label Apr 8, 2016

fehguy reviewed Apr 8, 2016
View reviewed changes

webron reviewed Apr 11, 2016
View reviewed changes

IvanGoncharov mentioned this pull request Apr 11, 2016

OpenAPI.next: Allow recursive paths #647

Closed

This was referenced Apr 11, 2016

Group multiple parameter definitions for better maintainability OAI/Overlay-Specification#34

Closed

Global/common parameters #341

Closed

Allow implicit path parameter matching #132

Closed

ePaul mentioned this pull request Apr 12, 2016

Issue #577: interface for paths #650

Closed

fehguy added 4 commits April 19, 2016 23:48

updated from schemas to components

ed4f8ad

updated from schemas to components

6c1415f

updated from schemas to components

2047542

updated from schemas to components

e1c5108

fehguy merged commit 082772c into OpenAPI.next Apr 20, 2016

ePaul reviewed Apr 20, 2016
View reviewed changes

ePaul added a commit to ePaul/OpenAPI-Specification that referenced this pull request Apr 20, 2016

Issue OAI#577: put the interfaces object into the components object f…

19f8cfd

…rom OAI#633. Also, rename it to "Interfaces Definitions Object".

fehguy deleted the issue-563 branch October 20, 2016 17:12

handrews added a commit to handrews/OpenAPI-Specification that referenced this pull request Oct 11, 2024

Merge pull request OAI#633 from OAI/issue-563

9eb70fb

moved reusable definitions under a single element [Manually ported merge] Co-authored-by: Tony Tam <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

moved reusable definitions under a single element #633

moved reusable definitions under a single element #633

fehguy commented Apr 8, 2016

fehguy Apr 8, 2016

ePaul Apr 8, 2016

darrelmiller Apr 9, 2016

webron Apr 11, 2016

earth2marsh Apr 14, 2016

fehguy commented Apr 8, 2016

webron Apr 11, 2016

webron commented Apr 11, 2016

fehguy commented Apr 11, 2016

IvanGoncharov commented Apr 11, 2016

jharmn commented Apr 13, 2016

ePaul commented Apr 13, 2016

earth2marsh commented Apr 14, 2016

jharmn commented Apr 14, 2016

fehguy commented Apr 15, 2016

ePaul Apr 20, 2016

moved reusable definitions under a single element #633

moved reusable definitions under a single element #633

Conversation

fehguy commented Apr 8, 2016

fehguy Apr 8, 2016

Choose a reason for hiding this comment

ePaul Apr 8, 2016

Choose a reason for hiding this comment

darrelmiller Apr 9, 2016

Choose a reason for hiding this comment

webron Apr 11, 2016

Choose a reason for hiding this comment

earth2marsh Apr 14, 2016

Choose a reason for hiding this comment

fehguy commented Apr 8, 2016

webron Apr 11, 2016

Choose a reason for hiding this comment

webron commented Apr 11, 2016

fehguy commented Apr 11, 2016

IvanGoncharov commented Apr 11, 2016

jharmn commented Apr 13, 2016

ePaul commented Apr 13, 2016

earth2marsh commented Apr 14, 2016

jharmn commented Apr 14, 2016

fehguy commented Apr 15, 2016

ePaul Apr 20, 2016

Choose a reason for hiding this comment