This question already has an answer here:
Reusing a subset of an enum in OpenAPI (Swagger)
(1 answer)
Closed 2 years ago.
Let's say in my OpenAPI v3 description, I have the following /componenets/schemas entry (using YAML) format:
WidgetTypes:
type: string
enum:
- WIDGET_A
- WIDGET_B
- WIDGET_C
The WidgetTypes schema is thus a named (i.e. value $ref) enum 'class'. In various other places in the API spec, we can now refer to these enum values, e.g. perhaps there's an API path for which one of the path elements must come from the WidgetTypes set.
Now, I have also some additional schemas (i.e. object data models), and there might be a case where a specific WidgetType value is a constant for that object type. An example:
MySpecificWidgetA:
type: object
properties:
someField1:
type: string
someField2:
type: number
widgetType:
type: string
enum:
- WIDGET_A
This feels like the naïve way to accomplish this, since now MySpecificWidgetA's widgetType field is a string that comes from the set of possible WidgetType's, but there's no actual reference to WidgetType enforcing this.
In spirit, what I'd like to assert is that MySpecificWidgetA.widgetType is a specific value from the WidgetType enum schema (in this case WIDGET_A).
Using just $ref: '#/components/schemas/WidgetType' passes validation, but doesn't accomplish what I want: it states widgetType is simply a value coming from that set ... I want it to be a restricted value from that set (i.e. a constant).
I've tried experimenting with $ref a few other ways for the value of widgetType, including (without success):
$ref: '#/components/schemas/WidgetType/WIDGET_A'
$ref: '#/components/schemas/WidgetType/enum/WIDGET_A'
$ref: '#/components/schemas/WidgetType/enum/0'
(the last one being not very useful, but just testing out the exact JSON Pointer format that $ref uses.)
None of these attempts above pass the OpenAPI v3 validation ... does anyone know if it's possible to reference (via $ref or some other mechanism) a specific value from a defined enum schema element?
This is not allowed by JSON Schema. $ref is only allowed to resolved to other schema objects, not to individual data points.
Related
We already have flatbuffer library embedded in our software code for simple schemas with JSON output data generation.
More update: We are generating the header files using flatc compiler against the schema and integrate these files inside of our code along with FB library for further serialization/deserialization.
Now we also need to have the following schema tree to be supported.
namespace SampleNS;
/// user defined key value pairs to add custom metadata
/// key namespacing is the responsibility of the user
table KeyValue {
key:string (key, required);
value:string (required);
}
enum SchemaVersion:byte {
V1,
V2
}
table Sometable {
value1:ubyte;
value2:ushort (key);
}
table ComponentData {
inputs: [Sometable];
outputs: [Sometable];
}
table Node {
name:string (key);
/// IO definition
data:ComponentData;
/// nested child
child:[Components];
}
table Components {
type:ubyte;
index:ubyte;
nodes:[Node];
}
table GroupMasterData {
schemaversion:SchemaVersion = sampleNS::SchemaVersion::V1;
metainfo:[KeyValue];
/// List of expected components in the system
components:[Components];
}
root_type GroupMasterData;
As from above, table Components is nested recursively. The intention is components may have childs that have the same fields.
I have few queries:
Flatc didnt gave me any error during schema compilation for such
recursive nested tables. But is this supported during the field
access for such tables?
I tried to generate a sample json data file based on above data but I
could not see the field for schemaversion. I learned FB doesn't
serialize the default values. so, I removed the default value that I
assigned in the schema. But, it still doesnt write into the json data
file. On this I also learned we can forcefully write into the file
using force_defaults option. I don't know where is this is to be
put: in the attribute or elsewhere?
Can I create a struct of enum field?
Is their any API to set Flatbuffer options that we otherwise pass to the compiler arguments? or if not, may be I think we have to tinker with the FB library code. Please suggest.
Method 1:
In our serialization method, we do this:
flatbuffers::Parser* parser = new flatbuffers::Parser();
parser->opts.output_default_scalars_in_json = true;
Is this the right method or should I use any other API?
Yes, trees (and even DAG) structures are fully supported. The type definition is recursive, but the data will eventually have leaf nodes with an empty vector of children, presumably.
The integer value for V1 is 0, and that is also the default value for all fields with no explicit default assigned. Use --defaults-json to see this field when converting. Note that explicit versions in a schema is an anti-pattern, since schemas are naturally evolvable without breaking backwards compatibility.
You can put enum fields in structs, yes. Is that what you mean?
In my RAML 1.0 spec, I would like to represent a uriParameter whose value is one of a set list of enumerated tokens. For example, _format can only be one of: csv, json or ttl.
As far as I can tell from reading the RAML spec, that's not possible at the moment unless I include JSON schema declarations. Can RAML encode enums without JSON schema, and if so, how?
Yes you can, by using RAML 1 data types:
"Data types can describe a base or resource URI parameter, a query parameter, a request or response header, or a request or response body. Data types are built-in or custom. A built-in type can be used anywhere the API expects data. Custom types can be defined by extending the built-in types as well as named and used like built-in type"
Example:
#%RAML 1.0
title: bla
types:
foo:
type: string
enum: [ json, csv, ttl ]
/bar/{_format}:
uriParameters:
_format:
type: foo
get:
Using Microsoft Bond (the C# library in particular), I see that whenever a Bond struct is defined, it looks like this:
struct Name
{
0: type name;
5: type name;
...
}
What do these numbers (0, 5, ...) mean?
Do they require special treatment in inheritance? (Do I need to make sure that I do not override members with the same number defined in my ancestor?)
The field ordinals are the unique identity of each field. When serializing to tagged binary protocols, these numbers are used to indicate which fields are in the payload. The names of the fields are not used. (Renaming a field in the .bond file does not break serialized binary data compatibility [though, see caveat below about text protocols].) Numbers are smaller than strings, which helps reduce the payload size, but also ends up improving serialization/deserialization time.
You cannot re-use the same field ordinal within the same struct.
There's no special treatment needed when you inherit from a struct (or if you have a struct field inside your struct). Bond keeps the ordinals for the structs separate. Concretely, the following is legal and will work:
namespace inherit_use_same_ordinal;
struct Base {
0: string field;
}
struct Derived : Base {
0: bool field;
}
A caveat about text serialization protocols like Simple JSON and Simple XML: these protocols use the field name as the field identifier. So, in these protocols renaming a field breaks serialized data compatibility.
Also, Simple JSON and Simple XML flatten the inheritance hierarchy, so re-using names across Base and Derived will result in clashes. Both have ways to work around this. For Simple XML, the SimpleXml.Settings.UseNamespaces parameter can be set to true to emit fully qualified names.
For Simple JSON, the Bond attribute JsonName can be used to change the name used for Simple JSON serialization, to avoid the conflict:
struct Derived : Base {
[JsonName("derived_field")]
0: bool field;
}
I use the graph version of OrientDB. Now I created a schema-less class, where I want to index a variable. This variable needs to become a property first. But when I try to create this property - of type string (or binary, or whatever) - it responds:
com.orientechnologies.orient.core.exception.OSchemaException: The database contains some schema-less data in the property 'clazz.clazz_name' that is not compatible with the type STRING. Fix those records and change the schema again [ONetworkProtocolHttpDb]
So I need to fix something, but what? What characters are illegal for a variable to become a property so that it can be indexed? (BTW, lists are also not an option)
There was indeed a problem I created.
I created a super-class where the property had to be created. One of the sub-classes inserted a List instead of a String. So when querying all vertices of sub-type
final Iterable<Vertex> iterable = this.graph.getVerticesOfClass("clazz");
I printed all types of clazz_name by vertex.getProperty("clazz_name").getClass().getName() where I saw OLinkedList. Reinserting those vertices fixed my problem.
I would like to create an EA Script to configure (add/edit/delete) the Defined Tag Types (Settings > UML Types > Tagged Value Types) similar to what is done manually here.
I did not found any useful information about the object storing the Defined Tag Types. Any help?
This configuration is not available in EA's API. If you want to make changes to it programmatically, you'll have to manipulate the project database directly.
The "Tagged Value Types" are stored in the t_propertytypes table. Please note that tagged value types defined in an MDG Technology are not listed here, this table only contains those that are shown in the "UML Types" dialog.
Looks like that you can programmatically only read the Tagged Values and change their value. Apparently you cannot add/remove Tagged Values.
Here is a part of the corresponding API. To add/remove a tagged value, you have to go directly to the DB.
TaggedValue Methods:
Method
Type
Notes
GetAttribute(string propName)
String
Returns the text of a single named property within a structured Tagged Value.
Parameters:
· propName: String - the name of the property for which the text is being returned
GetLastError()
String
Returns a string value describing the most recent error that occurred in relation to this object.
HasAttributes()
Boolean
Returns true if the Tagged Value is a structured Tagged Value with one or more properties.
SetAttribute(
string propName,
string propValue)
Boolean
Sets the text of a single named property within a structured Tagged Value.
Parameters:
· propName: String - - the name of the property for which the text is being set
· propValue: the value of the property
Update()
Boolean
Updates the current TaggedValue object after modification or appending a new item.
If false is returned, check the GetLastError function for more information.