Skip to content

Commit e0fbf14

Browse files
mrainerimraineri
committed
Initial commit
0 parents  commit e0fbf14

File tree

10 files changed

+1277
-0
lines changed

10 files changed

+1277
-0
lines changed

‎AUTHORS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Original Contribution:
2+
3+
* [Matthew Kocurek](//github.com/Yergidy) - HPE - Hewlett Packard Enterprise Restful API Group

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Change Log
2+
3+
## [0.9.0] - 2020-09-27
4+
- Initial release

‎LICENSE.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
The Distributed Management Task Force (DMTF) grants rights under copyright in
2+
this software on the terms of the BSD 3-Clause License as set forth below; no
3+
other rights are granted by DMTF. This software might be subject to other rights
4+
(such as patent rights) of other parties.
5+
6+
7+
### Copyrights.
8+
9+
Copyright (c) 2020, Contributing Member(s) of Distributed Management Task Force,
10+
Inc.. All rights reserved.
11+
12+
Redistribution and use in source and binary forms, with or without modification,
13+
are permitted provided that the following conditions are met:
14+
15+
* Redistributions of source code must retain the above copyright notice, this
16+
list of conditions and the following disclaimer.
17+
* Redistributions in binary form must reproduce the above copyright notice, this
18+
list of conditions and the following disclaimer in the documentation and/or
19+
other materials provided with the distribution.
20+
* Neither the name of the Distributed Management Task Force (DMTF) nor the names
21+
of its contributors may be used to endorse or promote products derived from this
22+
software without specific prior written permission.
23+
24+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
25+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
26+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
27+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
28+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
29+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
31+
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34+
35+
36+
### Patents.
37+
38+
This software may be subject to third party patent rights, including provisional
39+
patent rights ("patent rights"). DMTF makes no representations to users of the
40+
standard as to the existence of such rights, and is not responsible to
41+
recognize, disclose, or identify any or all such third party patent right,
42+
owners or claimants, nor for any incomplete or inaccurate identification or
43+
disclosure of such rights, owners or claimants. DMTF shall have no liability to
44+
any party, in any manner or circumstance, under any legal theory whatsoever, for
45+
failure to recognize, disclose, or identify any such third party patent rights,
46+
or for such party's reliance on the software or incorporation thereof in its
47+
product, protocols or testing procedures. DMTF shall have no liability to any
48+
party using such software, whether such use is foreseeable or not, nor to any
49+
patent owner or claimant, and shall have no liability or responsibility for
50+
costs or losses incurred if software is withdrawn or modified after publication,
51+
and shall be indemnified and held harmless by any party using the software from
52+
any and all claims of infringement by a patent owner for such use.
53+
54+
DMTF Members that contributed to this software source code might have made
55+
patent licensing commitments in connection with their participation in the DMTF.
56+
For details, see http://dmtf.org/sites/default/files/patent-10-18-01.pdf and
57+
http://www.dmtf.org/about/policies/disclosures.

‎README.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Redfish Schema Creator
2+
3+
Copyright 2020 DMTF. All rights reserved.
4+
5+
## About
6+
7+
The most efficient method of crafting a new schema has been to first create a mockup of the data as a JSON payload. Once the data makes sense in that form, sometimes with the addition of a property description list, a schema is then prepared.
8+
9+
This utility will read a JSON document and using the Redfish conventions and some optional annotations, output a "mostly complete" CSDL Redfish schema file. In addition, as typing the Description and LongDescription text can be cumbersome within a CSDL document, and may have been written in a spreadsheet or other tool prior to schema creation, the utility will also merge a CSV file to incorporate description text into the schema output.
10+
11+
12+
## Usage
13+
14+
```
15+
usage: csdl_creator.py [-h] [--desc DESC] [--csv CSV] [--toggle] json
16+
17+
Builds a mostly complete CSDL file from an annotated JSON file and an optional
18+
CSV file.
19+
20+
positional arguments:
21+
json file to process
22+
23+
optional arguments:
24+
-h, --help show this help message and exit
25+
--desc DESC sysdescription for identifying logs
26+
--csv CSV csv file of helpful definitions for this file
27+
--toggle print a csv report at the end of the log
28+
```
29+
30+
## JSON document
31+
32+
The input document must be valid JSON. The following schema attributes will be determined directly from the JSON payload:
33+
* Schema name (value of @odata.type)
34+
* Property names
35+
* Data types (string, integer, number/float, boolean)
36+
* Array definitions (item type from data type)
37+
* Enum values - string with "|" separators between enum values e.g. "On | Off | Blinking"
38+
* Embedded object hierarchy
39+
* Links objects and navigation properties (object with @odata.id property)
40+
* Actions definitions from Actions object
41+
* References to properties in Resource_v1 can be detected and referenced
42+
* If annotated, include schema reference for any links
43+
44+
45+
### Annotations
46+
47+
The addition of property-level annotations aid in completing the schema creation. An annotation is constructed using the property name with a "!" separator and annotation name appended. Defined annotations include:
48+
* <property>!description - Description text
49+
* <property>!longDescription - Long Description text
50+
* <property>!link - Schema name for link target (populate property and schema reference)
51+
* <property>!readonly - mark property as R/W instead of R/O (default is R/O)
52+
* <property>!required - mark property as Required
53+
54+
55+
### Sample annotated JSON
56+
57+
```json
58+
{
59+
"@odata.id": "/redfish/v1/Thingy/1",
60+
"@odata.type": "#Thingy.v1_0_0.Thingy",
61+
"Id": "1",
62+
"Name": "Big Thingy",
63+
"ThingType": "RackMount | Cheap | Expensive | Obsolete | Trendy",
64+
"ThingType!required": true,
65+
"ThingType!description": "The type of thingy that this thingy is - really...",
66+
"IndicatorLED": "Off | Lit | Blinking",
67+
"IndicatorLED!readonly": false,
68+
"Location": { },
69+
"Status": {
70+
"State": "Enabled",
71+
"Health": "OK"
72+
},
73+
"PCIeSlots": {
74+
"@odata.id": "/redfish/v1/Chassis/1/PCIeSlots"
75+
},
76+
"PCIeSlots!link": "PCIeDevice",
77+
"Thermal": {
78+
"@odata.id": "/redfish/v1/Chassis/1/Thermal"
79+
},
80+
"Thermal!link": "Thermal",
81+
"Power": {
82+
"@odata.id": "/redfish/v1/Chassis/1/Power"
83+
}
84+
}
85+
```
86+
87+
## Supplemental CSV file
88+
89+
A comma-separated variable (CSV) file can be specified as input to provide description text, using the following:
90+
91+
`<property name>, <description>, <long description>`
92+
93+
The property name could also provide a JSON path `object/property` or similar style to allow inclusion of properties within embedded objects.
94+
95+
96+
## XML header file
97+
98+
An XML file with the default comment block header, follow existing Redfish schema, with keyword for schema name replacement.
99+
100+
101+
## Schema output
102+
103+
The utility will process the JSON document and CSV file, if provided, to produce a Redfish CSDL schema file with incomplete data notated for user to provide, and reasonable defaults taken for other attributes that cannot be determined.
104+
105+
Default property attributes:
106+
* Properties marked as read-only
107+
* Properties non-nullable
108+
* Schema version and namespace is v1.0.0
109+
110+
Default inclusions:
111+
* Actions block
112+
* Capabilities block
113+
* OEM block
114+
115+
Default text:
116+
* "***TBD***" strings for Description and LongDescription text if not found in payload or CSV
117+
* "***TBD***" names for linked schemas and types if not provided in annotations.
118+
* Generic description/longDescription for links based on existing Redfish style

‎Thingy.v1_0_0.xml‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
<!---->
2+
<!--################################################################################ -->
3+
<!--# Redfish Schema: Thingy.v1_0_0 -->
4+
<!--# -->
5+
<!--# For a detailed change log, see the README file contained in the DSP8010 bundle, -->
6+
<!--# available at http://www.dmtf.org/standards/redfish -->
7+
<!--# Copyright 2020 DMTF. -->
8+
<!--# For the full DMTF copyright policy, see http://www.dmtf.org/about/policies/copyright -->
9+
<!--################################################################################ -->
10+
<!---->
11+
<?xml version="1.0" ?>
12+
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
13+
<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/Resource_v1.xml">
14+
<edmx:Include Namespace="Resource.v1_0_0"/>
15+
</edmx:Reference>
16+
<edmx:Reference Uri="http://docs.oasis-open.org/odata/odata/v4.0/errata03/csd01/complete/vocabularies/Org.OData.Capabilities.V1.xml">
17+
<edmx:Include Namespace="Org.OData.Capabilities.V1" Alias="Capabilities"/>
18+
</edmx:Reference>
19+
<edmx:Reference Uri="http://docs.oasis-open.org/odata/odata/v4.0/errata03/csd01/complete/vocabularies/Org.OData.Core.V1.xml">
20+
<edmx:Include Namespace="Org.OData.Core.V1" Alias="OData"/>
21+
</edmx:Reference>
22+
<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/Power_v1.xml">
23+
<edmx:Include Namespace="Power"/>
24+
</edmx:Reference>
25+
<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/Thermal_v1.xml">
26+
<edmx:Include Namespace="Thermal"/>
27+
</edmx:Reference>
28+
<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/PCIeDevice_v1.xml">
29+
<edmx:Include Namespace="PCIeDevice"/>
30+
</edmx:Reference>
31+
<edmx:Reference Uri="http://redfish.dmtf.org/schemas/v1/RedfishExtensions_v1.xml">
32+
<edmx:Include Namespace="RedfishExtensions.v1_0_0" Alias="Redfish"/>
33+
</edmx:Reference>
34+
<edmx:DataServices>
35+
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Thingy">
36+
<Annotation Term="Redfish.OwningEntity" String="TBD"/>
37+
<EntityType Name="Thingy" BaseType="Resource.v1_0_0.Resource" Abstract="true">
38+
<Annotation Term="OData.Description" String="Parameters for Thingy."/>
39+
<Annotation Term="OData.LongDescription" String="Parameters for Thingy."/>
40+
<Annotation Term="Capabilities.InsertRestrictions">
41+
<Record>
42+
<PropertyValue Property="Insertable" Bool="false"/>
43+
</Record>
44+
</Annotation>
45+
<Annotation Term="Capabilities.UpdateRestrictions">
46+
<Record>
47+
<PropertyValue Property="Updatable" Bool="false"/>
48+
</Record>
49+
</Annotation>
50+
<Annotation Term="Capabilities.DeleteRestrictions">
51+
<Record>
52+
<PropertyValue Property="Deletable" Bool="false"/>
53+
</Record>
54+
</Annotation>
55+
</EntityType>
56+
</Schema>
57+
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Thingy.v1_0_0">
58+
<Annotation Term="Redfish.OwningEntity" String="TBD"/>
59+
<Annotation Term="Redfish.Release" String="TBD"/>
60+
<EntityType Name="Thingy" BaseType="Thingy.Thingy">
61+
<Property Name="ThingType" Type="Thingy.v1_0_0.ThingType" Nullable="false">
62+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
63+
<Annotation Term="OData.Description" String="The type of thingy that this thingy is - really..."/>
64+
<Annotation Term="OData.LongDescription" String="A long thingy description..."/>
65+
<Annotation Term="Redfish.Required"/>
66+
</Property>
67+
<Property Name="IndicatorLED" Type="Resource.IndicatorLED" Nullable="false">
68+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
69+
<Annotation Term="OData.Description" String="TBD"/>
70+
<Annotation Term="OData.LongDescription" String="TBD"/>
71+
</Property>
72+
<Property Name="SideFumbling" Type="Edm.Boolean" Nullable="false">
73+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/ReadWrite"/>
74+
<Annotation Term="OData.Description" String="TBD"/>
75+
<Annotation Term="OData.LongDescription" String="TBD"/>
76+
</Property>
77+
<Property Name="Location" Type="Resource.Location" Nullable="false">
78+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
79+
<Annotation Term="OData.Description" String="TBD"/>
80+
<Annotation Term="OData.LongDescription" String="TBD"/>
81+
</Property>
82+
<Property Name="LotsOfStuff" Type="Collection(Edm.String)" Nullable="false">
83+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
84+
<Annotation Term="OData.Description" String="TBD"/>
85+
<Annotation Term="OData.LongDescription" String="TBD"/>
86+
</Property>
87+
<Property Name="LotsOfStuff2" Type="Collection(Edm.Int64)" Nullable="false">
88+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
89+
<Annotation Term="OData.Description" String="TBD"/>
90+
<Annotation Term="OData.LongDescription" String="TBD"/>
91+
</Property>
92+
<Property Name="LotsOfStuff3" Type="Collection(Thingy.v1_0_0.LotsOfStuff3)" Nullable="false">
93+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
94+
<Annotation Term="OData.Description" String="TBD"/>
95+
<Annotation Term="OData.LongDescription" String="TBD"/>
96+
</Property>
97+
<Property Name="LotsOfStuff4" Type="Collection(Thingy.v1_0_0.LotsOfStuff4)" Nullable="false">
98+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
99+
<Annotation Term="OData.Description" String="TBD"/>
100+
<Annotation Term="OData.LongDescription" String="TBD"/>
101+
</Property>
102+
<Property Name="ThingContainer" Type="Thingy.v1_0_0.ThingContainer" Nullable="false">
103+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
104+
<Annotation Term="OData.Description" String="TBD"/>
105+
<Annotation Term="OData.LongDescription" String="TBD"/>
106+
</Property>
107+
<Property Name="Status" Type="Resource.Status" Nullable="false">
108+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
109+
<Annotation Term="OData.Description" String="TBD"/>
110+
<Annotation Term="OData.LongDescription" String="TBD"/>
111+
</Property>
112+
<NavigationProperty Name="PCIeSlots" Type="Collection(PCIeDevice.PCIeDevice)" Nullable="false">
113+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
114+
<Annotation Term="OData.Description" String="A link to PCIeSlots"/>
115+
<Annotation Term="OData.LongDescription" String="This property shall be a link to a resource collection of type PCIeSlots."/>
116+
<Annotation Term="OData.AutoExpandReferences"/>
117+
</NavigationProperty>
118+
<NavigationProperty Name="Thermal" Type="Thermal.Thermal" Nullable="false">
119+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
120+
<Annotation Term="OData.Description" String="A link to Thermal"/>
121+
<Annotation Term="OData.LongDescription" String="This property shall be a link to a resource collection of type Thermal."/>
122+
</NavigationProperty>
123+
<NavigationProperty Name="Power" Type="Power.Power" Nullable="false">
124+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
125+
<Annotation Term="OData.Description" String="A link to Power"/>
126+
<Annotation Term="OData.LongDescription" String="This property shall be a link to a resource collection of type Power."/>
127+
</NavigationProperty>
128+
<NavigationProperty Name="Power2" Type="Power.Power" Nullable="false">
129+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
130+
<Annotation Term="OData.Description" String="A link to Power2"/>
131+
<Annotation Term="OData.LongDescription" String="This property shall be a link to a resource collection of type Power2."/>
132+
</NavigationProperty>
133+
</EntityType>
134+
<EnumType Name="ThingType">
135+
<Member Name="RackMount">
136+
<Annotation Term="OData.Description" String="tmp"/>
137+
</Member>
138+
<Member Name="Cheap">
139+
<Annotation Term="OData.Description" String="tmp1"/>
140+
</Member>
141+
<Member Name="Expensive">
142+
<Annotation Term="OData.Description" String="tmp2"/>
143+
</Member>
144+
<Member Name="Obsolete">
145+
<Annotation Term="OData.Description" String="tmp3"/>
146+
</Member>
147+
<Member Name="Trendy">
148+
<Annotation Term="OData.Description" String="tmp4"/>
149+
</Member>
150+
</EnumType>
151+
<EnumType Name="LotsOfStuff3">
152+
<Member Name="a">
153+
<Annotation Term="OData.Description" String="TBD"/>
154+
</Member>
155+
<Member Name="b">
156+
<Annotation Term="OData.Description" String="TBD"/>
157+
</Member>
158+
<Member Name="c">
159+
<Annotation Term="OData.Description" String="TBD"/>
160+
</Member>
161+
</EnumType>
162+
<ComplexType Name="LotsOfStuff4" Nullable="false">
163+
<Annotation Term="OData.Description" String="TBD"/>
164+
<Annotation Term="OData.LongDescription" String="TBD"/>
165+
<Annotation Term="OData.AdditionalProperties" Bool="false"/>
166+
<Property Name="My_Name" Type="Edm.String" Nullable="false">
167+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
168+
<Annotation Term="OData.Description" String="TBD"/>
169+
<Annotation Term="OData.LongDescription" String="TBD"/>
170+
</Property>
171+
</ComplexType>
172+
<ComplexType Name="ThingButton" Nullable="false">
173+
<Annotation Term="OData.Description" String="TBD"/>
174+
<Annotation Term="OData.LongDescription" String="TBD"/>
175+
<Annotation Term="OData.AdditionalProperties" Bool="false"/>
176+
<Property Name="ButtonColor" Type="Edm.String" Nullable="false">
177+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
178+
<Annotation Term="OData.Description" String="Color of the button."/>
179+
<Annotation Term="OData.LongDescription" String="TBD"/>
180+
</Property>
181+
<Property Name="ButtonActuation" Type="Edm.Decimal" Nullable="false">
182+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
183+
<Annotation Term="OData.Description" String="TBD"/>
184+
<Annotation Term="OData.LongDescription" String="TBD"/>
185+
<Annotation Term="Redfish.Required"/>
186+
</Property>
187+
</ComplexType>
188+
<ComplexType Name="ThingContainer" Nullable="false">
189+
<Annotation Term="OData.Description" String="TBD"/>
190+
<Annotation Term="OData.LongDescription" String="TBD"/>
191+
<Annotation Term="OData.AdditionalProperties" Bool="false"/>
192+
<Property Name="ThingKnob" Type="Edm.String" Nullable="false">
193+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
194+
<Annotation Term="OData.Description" String="TBD"/>
195+
<Annotation Term="OData.LongDescription" String="TBD"/>
196+
</Property>
197+
<Property Name="ThingKnobCount" Type="Edm.Int64" Nullable="false">
198+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
199+
<Annotation Term="OData.Description" String="TBD"/>
200+
<Annotation Term="OData.LongDescription" String="TBD"/>
201+
</Property>
202+
<Property Name="ThingButton" Type="Thingy.v1_0_0.ThingButton" Nullable="false">
203+
<Annotation Term="OData.Permissions" EnumMember="OData.Permission/Read"/>
204+
<Annotation Term="OData.Description" String="TBD"/>
205+
<Annotation Term="OData.LongDescription" String="TBD"/>
206+
</Property>
207+
</ComplexType>
208+
</Schema>
209+
</edmx:DataServices>
210+
</edmx:Edmx>
211+

0 commit comments

Comments
 (0)