Difference between revisions of "Resource Registry Service - Type Management"
Luca.frosini (Talk | contribs) m (→Basic Types) |
Luca.frosini (Talk | contribs) (→Type Definition) |
||
Line 41: | Line 41: | ||
* '''abstractType''' (Boolean): Indicate if the type is abstract so that it cannot be instantiated. In other words, only subtypes of this type can be instantiated. <code>default=false</code>. | * '''abstractType''' (Boolean): Indicate if the type is abstract so that it cannot be instantiated. In other words, only subtypes of this type can be instantiated. <code>default=false</code>. | ||
* '''superclasses''' (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported. | * '''superclasses''' (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported. | ||
− | * '''properties''': any types, except Resource and its specialisation, includes a properties array [List]. Any [[#Property] is described by a set of attributes. | + | * '''properties''': any types, except Resource and its specialisation, includes a properties array [List]. Any [[#Property]] is described by a set of attributes. |
* '''version''': the actual version of the type; | * '''version''': the actual version of the type; | ||
* '''changelog''': the history of changes in the type representation. It is an object containing properties with version as key and the change description as values. | * '''changelog''': the history of changes in the type representation. It is an object containing properties with version as key and the change description as values. | ||
Line 50: | Line 50: | ||
** '''name'''*: the property name [String]; | ** '''name'''*: the property name [String]; | ||
− | ** '''type'''*: The Type of the Property (e.g. String, Integer, ...). See [[# | + | ** '''type'''*: The Type of the Property (e.g. String, Integer, ...). See [[#Property_Types|Property Types]]; |
** '''description''': the description of the property [String, default=null]; | ** '''description''': the description of the property [String, default=null]; | ||
** '''mandatory''': indicate if the property is mandatory or not [String, default=false]; | ** '''mandatory''': indicate if the property is mandatory or not [String, default=false]; | ||
Line 59: | Line 59: | ||
** '''regex''': a [https://en.wikipedia.org/wiki/Regular_expression regular expression] to validate the property value [String, default=null]. A good online tool for regex is available at [https://regex101.com/ https://regex101.com/] | ** '''regex''': a [https://en.wikipedia.org/wiki/Regular_expression regular expression] to validate the property value [String, default=null]. A good online tool for regex is available at [https://regex101.com/ https://regex101.com/] | ||
− | ===== Basic Types ===== | + | ===== Property Types ===== |
+ | |||
+ | ====== Basic Types ====== | ||
{|class="wikitable" | {|class="wikitable" | ||
Line 123: | Line 125: | ||
|} | |} | ||
− | ===== Derived Types ===== | + | ====== Derived Types ====== |
The following are obtained using a String as real type and adding a validation regex. | The following are obtained using a String as real type and adding a validation regex. | ||
Line 154: | Line 156: | ||
|} | |} | ||
− | ===== Complex Types ===== | + | ====== Complex Types ====== |
Any property defined by composing basic types derives from [[#Property|Property]] type. | Any property defined by composing basic types derives from [[#Property|Property]] type. |
Revision as of 09:45, 2 July 2021
These sections provide information regarding how to interact with Resource Registry Service for Type Management. REST API are presented for each functionality.
Please note that the provided examples can intentionally hide some details in the response to avoid unneeded complexity.
Type Management
Type Management is responsible for managing the instantiation of the IS Model by allowing the definition of entities, relations and embedded types and their schema.
The exposed APIs are:
- Create: allows to create a new Type;
- Exists: allows to check if a Type exists;
- Read: allows to read a Type. This API allows also the listing of type and its subtypes by indicating hte query parameter polymorphic=true.
By indicating the polimorphic parameter and as {TYPE_NAME} on of the base type of the IS Model (i.e. Resource, Facet, IsRelatedTo, ConsistsOf), it is possibile to list all the types of such base type.
Type Collection
Operation | HTTP Method | URL |
---|---|---|
Create | PUT | /types/{TYPE_NAME}
|
Exists | HEAD | /types/{TYPE_NAME}
|
Read | GET | /types/{TYPE_NAME}[?polymorphic=false]
|
Type Definition
Any Type is described by the following attributes:
- name (String): Type Name
- description (String): The description of the Type.
default=null
. - abstractType (Boolean): Indicate if the type is abstract so that it cannot be instantiated. In other words, only subtypes of this type can be instantiated.
default=false
. - superclasses (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported.
- properties: any types, except Resource and its specialisation, includes a properties array [List]. Any #Property is described by a set of attributes.
- version: the actual version of the type;
- changelog: the history of changes in the type representation. It is an object containing properties with version as key and the change description as values.
Property
Any Property is described by the following attributes:
- name*: the property name [String];
- type*: The Type of the Property (e.g. String, Integer, ...). See Property Types;
- description: the description of the property [String, default=null];
- mandatory: indicate if the property is mandatory or not [String, default=false];
- readOnly: the property cannot change its value [Boolean, default=false];
- notNull: whether the property must assume a value diverse from ’null’ or not [Boolean, default=false];
- max: whether the property can be limited to a maximum value [Integer, default=null];
- min: whether the property can be limited to a minimum value [Integer, default=null];
- regex: a regular expression to validate the property value [String, default=null]. A good online tool for regex is available at https://regex101.com/
Property Types
Basic Types
Type | Java type | Description |
---|---|---|
Boolean | java.lang.Boolean or boolean
|
Handles only the values True or False. |
Integer | java.lang.Integer or int or java.math.BigInteger
|
32-bit signed Integers. |
Short | java.lang.Short or short
|
Small 16-bit signed integers. |
Long | java.lang.Long or long
|
Big 64-bit signed integers. |
Float | java.lang.Float or float
|
Decimal numbers. |
Double | java.lang.Double or double
|
Decimal numbers with high precision. |
Date | java.util.Date
|
Any date with the precision up to milliseconds. |
String | java.lang.String
|
Any string as alphanumeric sequence of chars. |
Property | ? extends org.gcube.informationsystem.model.reference.properties.Property
|
This is an Object contained inside the owner Entity and has no Header. It is reachable only by navigating the owner Entity. |
|
List<? extends org.gcube.informationsystem.model.reference.properties.Property> |
|
|
Set<? org.gcube.informationsystem.model.reference.properties.Property> |
|
Map<String,Property> | Map<String, ? extends org.gcube.informationsystem.model.reference.properties.Property>
|
Map of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity. |
Byte | java.lang.Byte or byte
|
Single byte. useful to store small 8-bit signed integers. |
Binary | java.lang.Byte[] or byte[]
|
Can contain any value as byte array. |
Derived Types
The following are obtained using a String as real type and adding a validation regex.
Type | Java type | Description |
---|---|---|
Enum | java.lang.Enum or enum
|
by default it is represented using the String representation of the Enum. So that the primitive type used will be String. The enumeration is checked by setting Regexpr property. The Regular Expression is auto-generated and it will be something like ^(FIRST-ENUM-STRING_REPRESENTATION|SECOND-ENUM-STRING_REPRESENTATION|...|LAST_ENUM_STRING_REPRESENTATION)$ .
Otherwise (if indicated using an annotation), it can be represented using the Integer value of the Enum. So that the primitive type used will be Integer. The enumeration is checked using |
UUID | java.util.UUID
|
String representation of the UUID. The check is obtained using the regular expression ^([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}){1}$
|
URL | java.net.URL
|
String representation of the URL. No check actually. |
URI | java.net.URI
|
String representation of the URI. No check actually. |
TypeVersion | org.gcube.informationsystem.utils.TypeVersion
|
A type representing and validating a version in the following format X.X.X Major(Integer).Minor(Integer).Revision(Integer) (e.g 1.0.0, 2.3.0, 2.0.1). The check is obtained using the regular expression ^[1-9][0-9]{0,}\.(0|([1-9][0-9]{0,}))\.(0|([1-9][0-9]{0,}))$ .
|
Complex Types
Any property defined by composing basic types derives from Property type.
Type Creation
PUT /resource-registry/schema/{ Type Name }
Description
Allow to create new Entity or Relation or Embedded Type.
Parameters
Name | Type | Required | Description |
---|---|---|---|
Type Name | String | true | The name of the new type to create |
Responses
Code | Type | Description |
---|---|---|
200 | String | The json representation of the newly created type (which is the same of the request) |
Examples
Resource Type Creation
PUT /resource-registry/schema/Actor
Request Body
{ "name":"Actor", "description":"Any entity (human or machine) playing an active role.", "abstractType":true, /* If the Resource cannot be instantiated */ "superclasses":["Resource"], /* Resource or any registered specialization. */ "properties":null /* MUST be null. The Resource cannot have any property. */ }
Facet Type Creation
PUT /resource-registry/schema/ContactFacet
Request Body
{ "name":"ContactFacet", "description":"This facet is expected to capture contact information", "abstractType": false, "superclasses":["Facet"], "properties":[ { "name":"name", "description":"First Name", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String*/ },{ "name":"eMail", "description": "A restricted range of RFC‑822 compliant email address. ... ", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":"^[a-z0-9._%+-]{1,128}@[a-z0-9.-]{1,128}$", "linkedType":null, "linkedClass":null, "type":7 /* String */ } ] }
IsRelatedTo Type Creation
PUT /resource-registry/schema/Hosts
Request Body
{ "name":"Hosts", "description": "…”, "abstractType":false, "superclasses":["IsRelatedTo"], "properties":[] }
ConsistsOf Type Creation
PUT /resource-registry/schema/HasContact
Request Body
{ "name":"HasContact", "description":"", "abstractType":true, "superclasses":["ConsistsOf"], "properties":[] }
Property Type Creation
PUT /resource-registry/schema/AccessPolicy
Request Body
{ "name":"AccessPolicy", "description":"", "abstractType":false, "superclasses":["Embedded"], "properties":[{ "name":"policy", "description":"", "mandatory":false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":”ValueSchema”, "type": 9 /* Embedded */ },{ "name":"note", "description":"", "mandatory": false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String */ }] }
Read Type Definition
GET /resource-registry/schema/{ Type Name }
Description
Allow to read Type Definition
Parameters
Name | Type | Required | Description |
---|---|---|---|
Type Name | String | true | The name of the type you want to retrieve the definition |
Responses
Code | Type | Description |
---|---|---|
200 | String | The json representation of the newly created type |
Examples
Resource Type
GET /resource-registry/schema/Actor
Response
{ "name":"Actor", "description":"Any entity (human or machine) playing an active role.", "abstractType":true, "superclasses":["Resource"], "properties":null }
Facet Type
GET /resource-registry/schema/ContactFacet
Response
{ "name":"ContactFacet", "description":"This facet is expected to capture contact information", "abstractType": false, "superclasses":["Facet"], "properties":[ { "name":"name", "description":"First Name", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String*/ },{ "name":"eMail", "description": "A restricted range of RFC‑822 compliant email address. ... ", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":"^[a-z0-9._%+-]{1,128}@[a-z0-9.-]{1,128}$", "linkedType":null, "linkedClass":null, "type":7 /* String */ } ] }
IsRelatedTo Type
GET /resource-registry/schema/Hosts
Response
{ "name":"Hosts", "description": "…”, "abstractType":false, "superclasses":["IsRelatedTo"], "properties":[] }
ConsistsOf Type
GET /resource-registry/schema/HasContact
Response
{ "name":"HasContact", "description":"", "abstractType":true, "superclasses":["ConsistsOf"], "properties":[] }
Property Type
GET /resource-registry/schema/AccessPolicy
Response
{ "name":"AccessPolicy", "description":"", "abstractType":false, "superclasses":["Embedded"], "properties":[{ "name":"policy", "description":"", "mandatory":false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":”ValueSchema”, "type": 9 /* Embedded */ },{ "name":"note", "description":"", "mandatory": false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String */ }] }