[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [OASIS Issue Tracker] (ODATA-1058) Add ability to annotate revisions with information on all elements
[ https://issues.oasis-open.org/browse/ODATA-1058?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Ralf Handl updated ODATA-1058:
------------------------------
Fix Version/s: V4.01_CSD02
Affects Version/s: V4.01_CSD01
Proposal:
The proposal is to create a 'Revision' term in the Core vocabulary that may be applied to any element. Elements defined in a schema may then evolve over time and with their complete revision history intact. The proposal is as follows:
<Term Name="Revision" Type="CsdlMetamodel.RevisionType">
<Annotation Term="OData.Description" String="Defines an annotation to mark a revision." />
</Term>
<ComplexType Name="RevisionType">
<Property Name="Version" Type="Edm.String">
<Annotation Term="OData.Description" String="An 'm.n.e' string value composed of three decimal values separated by '.'. These values express major, minor, and errata version numbers for this revision where 'm' is an integer representing a major version. Major versions are expected to provide similar but extended functionality, but may be incompatible in any way. The minor version 'n' may include additional features and may not remove any features from previous minor versions of the same major version. The set of allowable values must include all allowable values of previous minor versions of the same major version. The errata version 'e' is used to mark a change that fixes something that was broken in the including minor version. By its nature, an errata version may include incompatible changes to fix a prior version."/>
</Property>
<Property Name="Type" Type="CsdlMetamodel.RevisionKind">
<Annotation Term="Core.Description" String="An enumerated value expressing the type of revision." />
</Property>
<Property Name="Description" Type="String">
<Annotation Term="Core.Description" String="Text description of the reason for the revision." />
</Property>
</ComplexType>
<EnumType Name="RevisionKind">
<Member Name="Add"/>
<Member Name="Insert"/>
<Member Name="Change"/>
<Member Name="Delete"/>
<Member Name="Deprecate"/>
</EnumType>
was:
The proposal is to create a 'Revision' annotation that may be applied to any element. Elements defined in a schema may then evolve over time and with their complete revision history intact. The proposal is as follows:
<Term Name="Revision" Type="CsdlMetamodel.RevisionType">
<Annotation Term="OData.Description" String="Defines an annotation to mark a revision." />
</Term>
<ComplexType Name="RevisionType">
<Property Name="Version" Type="Edm.String">
<Annotation Term="OData.Description" String="An 'm.n.e' string value composed of three decimal values separated by '.'. These values express major, minor, and errata version numbers for this revision where 'm' is an integer representing a major version. Major versions are expected to provide similar but extended functionality, but may be incompatible in any way. The minor version 'n' may include additional features and may not remove any features from previous minor versions of the same major version. The set of allowable values must include all allowable values of previous minor versions of the same major version. The errata version 'e' is used to mark a change that fixes something that was broken in the including minor version. By its nature, an errada version may include incompatible changes to fix a prior version."/>
</Property>
<Property Name="Type" Type="CsdlMetamodel.RevisionKind">
<Annotation Term="OData.Description" String="An enumerated value expressing the type of revision." />
</Property>
<Property Name="Description" Type="String">
<Annotation Term="OData.Description" String="Text description of the reason for the revision." />
</Property>
</ComplexType>
<EnumType Name="RevisionKind">
<Member Name="Add"/>
<Member Name="Insert"/>
<Member Name="Change"/>
<Member Name="Delete"/>
<Member Name="Deprecate"/>
</EnumType>
Resolution: (was: Proposed resolution is to add the Term declaration above to Core.)
Component/s: Vocabularies
(was: CSDL XML)
(was: New in OData)
(was: CSDL JSON )
I like it, it nicely complements the SchemaVersion annotation on schema level.
1) Would a schema only contain Revision markers for the current schema version, or would they "accumulate" over time?
My preference would be to only have revision annotations for changes from the previous schema version to the current schema version, in which case the Version property would not be needed. The Description property can be replaced by annotating the annotation with Core.Description, so we could simplify the term to just have the Type property, or even to an unstructured term showing only the revision kind.
The Core.Links term can then be used with rel="predecessor-version" to provide a $metadata URL with appended $schemaversion for the predecessor version.
2) RevisionKind values: what's the difference between "Add" and "Insert"? What's the difference between "Delete" and "Deprecate"? Actually deleted model elements aren't in the schema any more, so they can't be deleted. My list of values would be "New", "Changed", "Deprecated".
> Add ability to annotate revisions with information on all elements
> ------------------------------------------------------------------
>
> Key: ODATA-1058
> URL: https://issues.oasis-open.org/browse/ODATA-1058
> Project: OASIS Open Data Protocol (OData) TC
> Issue Type: New Feature
> Components: Vocabularies
> Affects Versions: V4.01_CSD01
> Environment: Schema declarations
> Reporter: George Ericson
> Assignee: George Ericson
> Labels: Extension, Practices, Usability
> Fix For: V4.01_CSD02
>
>
> Currently there is no defined means to mark revisions to schema. Some organizations have solved this by convention of creating a new schema for each set of revisions, primarily related only by time.
> Each schema represents a new namespace, so we get a proliferation of namespaces. Type definitions are specific to namespaces, but since the evolving types really represent the same type declaration, they are sub classed across these namespaces. This creates an unnecessarily complex model.
--
This message was sent by Atlassian JIRA
(v6.2.2#6258)
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]