Support for Specific Metadata

[zdne]

Various toolings might have a need for a tooling-specific metadata at different point in blueprint. A solution would be to add a syntax construct that would be expected wherever a Markdown formatted discussion is expected and that would provide (potentially recursive) "key: value" notation.

E.g.:

# API 
API Description

+ Metadata
    + Key: `Value`

# Resource [/resource]
Resource Description 

+ Metadata
    + Key: `Value`
    + Key2:
        + Key3: `Value`

Which would be reflected in AST like

_version: 1.0
metadata:
name: API
description: "API Description\n\n"
metadata:
    key: Value
resourceGroups:
- name:
  description:
  metadata:
  resources:
  - name: Resource
    description: "Resource Description \n\n"
    metadata:
        key: Value    
        key2:
            key3: Value 
    uriTemplate: /resource
    model:
    parameters:
    headers:
    actions:

[rcrooks]

Not sure I understand the context -- is this something that would go into the metadata section of the blueprint?

[zdne]

@rcrooks

Sorry I have updated the description. Hope it is much clearer now. Let me know should there be any questions.

Thanks.

[dwcramer]

Why are there two metadata fields in the AST?

_version: 1.0
metadata:
name: API
description: "API Description\n\n"
metadata:
    key: Value

[zdne]

@dwcramer

The line #2 metadata are holding current blueprint global metadata.

It is a good point that we might want to distinguish these two. Please take this pseudo AST just as a mere sketch of what it could be.

Suggestions how to distinguish between global blueprint metadata and specific metadata (is it really needed?) welcomed!

[dwcramer]

@zdne Maybe just name the second one +UserMetadata (and usermetadata in the JSON) or something (LocalMetadata?).
I think specific metadata is indeed needed. We have the following use cases:

• Indicating what roles have authorization to use certain methods (used by Repose for RBAC).
• Indicating if a method is internal only.
• Pointing to external files resource to this method (kind of a special case, but useful)

You don't know what kinds of information users need to encode, but you can be certain that some users will have extra metadata and not being able to include it could be a deal-breaker.

[fosdev]

@zdne @dwcramer Do we need these different tags, or rather just use keys under the Metadata tag ala

+ Metadata
  + User:
    + key: `value`
  + Local:
     + key2: `value2`
  + Whatever:
    key: `value`

And possibly some filtering by Metadata keys in the AST?

[zdne]

@fosdev

Well the little inconstancy here is that the current 1A format is using the MultiMarkdown (and Jekyll/YAML)-style of metadata at the top of every blueprint file. E.g.

key1: <value>
key2: <value>

# API Name
API discussion here.

This is sort of global metadata to the blueprint.

What we want to do is to introduce specific metadata at pretty much an point like so:

Key1: <value>
Key2: <value>

# API Name
API discussion here.

+ Metadata
    + Key3: `<value>`

Which is little bit inconsistent with the 1A syntax for global metadata...

[dwcramer]

@fosdev +1 for GlobalMetadata v. Metadata

[fosdev]

@zdne Ok, so seems the simple one is to have one tag that is GlobalMetadata (which would show up in your YAML as globalMetadata) and the other more generic, though that may cause some backwards compatibility issues, if I understand the situation.

I think that the idea of arbitrary metadata is keep it arbitrary vs. locked to specific keys that are limiting over time and maybe only specify specific Metadata tags for internal metadata for blueprint to separate it from user specified metadata. Make any sense?

[zdne]

Also refer to #27

[zdne]

Gentlemen,
I would love to fully address the needs for metadata by #47 – Traits. Thus closing this Milestone and not implementing the metadata as suggested here.

Please let me know what do you think and whether the concept of traits will address your expectation for metadata.

[rcrooks]

I am studying it with high hopes :)

Robert

On Tue, Dec 17, 2013 at 12:57 PM, Z [email protected] wrote:

Gentlemen,
I would love to fully address the needs for metadata by #47https://github.com/apiaryio/api-blueprint/issues/47– Traits. Thus closing this Milestone and
not implementing the metadata as suggested here.

Please let me know what do you think and whether the concept of traits
will address your expectation for metadata.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/38#issuecomment-30774179
.

Robert Crooks
Director of Learning Services | P: 617 245 5090 | M: 617-584 6128
Brightcove Inc http://www.brightcove.com/

[zdne]

@rcrooks

Implementing #47 will be one of my priorities for the next month or so as might expectations with it are high...

[zdne]

To be addressed (and closed) with #47.

[apimatic]

We would love to have tool-specific metadata on the per-api level. We have some flags and tokens that we use to generate custom code from API description. Mostly we will need booleans and strings. Having per-resource metadata is currently an overkill for us. However, I do see its usefulness e.g., to override some global settings. This feature will truly make API Blueprint superior to other formats.

[zdne]

Hey @apimatic were you able to work around this with https://apimatic.io/blog/post/api-blueprint-extension-for-code-generation-settings ? If not please lets discuss any additional needs here. Closing for now.

[apimatic]

Yes, the metadata parsing works great. We already have people who are using
these extensions. Thanks.

Kind Regards,

Zeeshan Ejaz Bhatti CTO / Co-Founder
[email protected] / +64211206721

APIMATIC Ltd.
132 Halsey St. Auckland Central, 1010, New Zealand
https://apimatic.io
http://t.signauxdix.com/e1t/c/5/f18dQhb0S7lC8dDMPbW2n0x6l2B9nMJW7t5XX43Lr8rnN5vwbZ-d0K3dVd_V9H56dQMcf6RTpv002?t=https%3A%2F%2Fapimatic.io%2F&si=4685392270852096&pi=76eaefbb-1a35-4e4f-f52c-0fef8e2a1560

Skype: zeeshan.ejaz
Book me for a Skype Call https://zeeshan.youcanbook.me/

On Wed, Dec 2, 2015 at 1:52 AM, Z [email protected] wrote:

Hey @apimatic https://github.com/apimatic were you able to work around
this with
https://apimatic.io/blog/post/api-blueprint-extension-for-code-generation-settings
? If not please lets discuss any additional needs here. Closing for now.

—
Reply to this email directly or view it on GitHub
#38 (comment)
.

[zdne]

Glad to hear! Thanks!