OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

odata-comment message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: Proposing additional annotations - Remarks and Notes


Hi Jeff,

 

StructuralPropertyNotes, NavigationPropertyNotes, and OperationNotes: as we can apply a given term to any model element, it would probably suffice to just add one term Notes that can be applied to structural properties, navigation properties, actions, and functions.

 

Which would lead us to

·         Description

·         LongDescription

·         Remarks

·         Notes

 

Is that the complete list, or would we find other specific terms if we take other documentation tools into account, maybe a Title for Swagger?

 

What would be the semantic difference between Notes, Remarks, and LongDescription?

 

Another way forward would be to say: ok, I need to differentiate between different flavors of LongDescription to satisfy the needs of my tool, so I define a set of qualifiers that give me that differentiation:

·         Core.Description becomes <summary>

·         Core.LongDescription becomes <remarks>

·         Core.LongDescription with Qualifier="Notes" becomes <notes>

·         And so on for all tool-specific documentation tags

 

What do you think?

 

Thanks in advance!

 

PS: I write this with my “TC member” hat on, so this is not an official statement of the TC

 

From: odata-comment@lists.oasis-open.org [mailto:odata-comment@lists.oasis-open.org] On Behalf Of Jeff Wight
Sent: Dienstag, 27. Oktober 2015 19:06
To: odata-comment@lists.oasis-open.org
Cc: Mark Stafford <mastaffo@microsoft.com>; Michael Pizzo <mikep@microsoft.com>
Subject: [odata-comment] Proposing additional annotations - Capabilities(SelectRestriction, UpsertSupported) - Core(ErrorCodes, CRUD Descriptions, Prerequisites)

 

Hi,

 

While going through exercises to better document our OData service, we came up with a collection of annotations we think we’d need in order to specify the rich content we’d like to express.

 

Here is a summary of some of the needs that I believe will be useful to any OData service:

Capabilities:

·         SelectRestrictions – Similar to Filter, Sort, and Expand Restrictions, we need the ability to specify if a collection supports $select, and which properties are non-selectable.

·         UpsertSupported – Fairly self-explanatory, a tag to indicate whether a given entity set supports Upsert.  We’d also like to considering how to differentiate PATCH vs PUT flavors of Upsert.

 

Core:

·         CRUD Descriptions – We already have the ability to identify which CRUD operations are supported on an entity set, using Insert, Update, and Delete Restrictions, but we’d like to be able to provide specific comments about these actions.  For example, a service that manages distribution lists may allow you POST to the /Users collection, meaning you are creating a user, however if you POST to the Distribution/BlockedSenders collection, this means you are blacklisting that user from being able to send mail to that group.  While one could imply this using the description of the entity set itself, it would allow us to be a bit more descriptive / contextual / clear here.

·         Operation ErrorCodes – Similar to how C# summary comments allow you to specify any <exception>s that a method may potentially throw, we would like to be able to specify the ErrorCodes that a given Operation may return, along with a blurb on what that error code means / how to resolve it.

·         Operation Prerequisites – Any special conditions that must be met before a caller should expect they can call an operation.  For example, an email service may expose a Send operation on an Email entity, but in order to invoke it, the email must have at least one of To:, CC:, or BCC: set.

 

In addition to the above, we have a need to expose the following as well, though I’m not sure they would be as generally useful to any OData service, but including here for discussion:

 

·         Entity Remarks – This is slightly different than Description or LongDescription, but similar to the <remarks> tag in c# summary documentation.

·         OAuth Scopes – Since our OData service support OAuth2, we’d like to be able to describe which OAuth scopes are required for interacting with an entity.  For example, an Email requires Mail.Read while an Event requires Calendar.Read.  It would also be nice to be able to specify that UPDATE and DELETE require the .ReadWrite permission.

·         Generic Schema Notes – These would be generic notes / footnotes on an entity that would apply to StructuralProperties, NavigationProperties, and Operations.  I would imagine this as StructuralPropertyNotes, NavigationPropertyNotes, and OperationNotes

 

Thoughts?

 

Thanks,
~Jeff

 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]