This document describes the metadata properties that the Cloud Elements platform expects when doing GET /objects/{objectName}/metadata. The GET /objects/{objectName}/metadata endpoint has strict formatting requirements to power our VDRs and also to keep consistency in object structure for the consumption of metadata. If not implemented properly, this can cause VDR's to fail, and cause the GET /objects/{objectName}/metadata endpoint to fail.
Goals of implementing /objects/{objectName}/metadata
- Provide a unified metadata experience across the platform
- Use javascript as necessary to convert from vendor meta format to CE format
- Provide users with as much data describing the API as the vendor makes available
- Power VDR's for all those gooooood transformations.
Watch Out! Your API needs to return data formatted exactly correct or the /objects/{objectName}/metadata API fails. We recommend creating a copy /objects/{objectName}/metadata_copy which doesn't have the same backend restrictions. Once you complete your resource, copy the hook over to the main API and let it take care of the validation for you
Best Practices
Below you will find a full list of acceptable properties for /objects/{objectName}/metadata and the usage, however, in practice, we often will only implement a fraction. This is usually due to the vendor not making things available, but you may also need to abstract something out that the platform doesn't support and is deemed unnecessary.
Always Include
vendorPath
- mask
- format
- type
Sometimes Include
When to include: nice-to-haves, if vendor provides property then implement it, but don't get caught up looking for them or doing insane parsing unless required
- vendorDisplayName
- vendorNativeType
- vendorReadOnly
- vendorRequired
- filterable
- createable
- updateable
- description
- custom
Seldom Include
When to include: Only implement these properties if a customer requires it, or you're just feeling really excited about having rich metadata
Path | primaryKey | custom | updateable | nullable | type |
reference | picklistValues[] | restrictedPicklist[] | relations | precision | defaultValue |
displayName | readOnly | filterable | method | description | conditionallyRequired |
vendorDisplayName | vendorRequired | filterableNames[] | name | length | subFormat |
vendorNativeType | vendorReadOnly | filterableOperators[] | response | minLength | sampleValue |
required | hidden | createable | request |
Dictionary
| CE Metadata Property Name | DataType | Description/Usage |
|---|---|---|
conditionallyRequired | String | when is this field required (dependency)… Invoice if CC provided, also need cvv. Mostly present in swagger |
createable | Boolean | can be created, usually in a POST |
custom | Boolean | true if is custom field |
defaultValue | Object | if no value provided, value defaults to X |
description | String | description of what field does |
displayName | String | label seen in vendor UI ** not used much |
filterable | Boolean | searchable in where clause |
filterableNames[] | List<String> | if prop filterable by other name, list filter options here. |
filterableOperators[] | List<String> | logical operators supported in filtering |
format | String | int64 |
hidden | Boolean | we don’t know what this means but vendors do it maybe hidden in UI |
length | Integer | max length of field |
| mask | String | formatting dates — usually only for dates |
method | List<ObjectMetadataFieldMethod> | name - HttpMethod in caps, GET POST PATCH ….. response - true/false does this field show up request - true/false can it be used in a request |
minLength | Integer | min length of field |
nullable | Boolean | most fields are nullable (default true). This field can/cannot be set to null (required)** |
| path | String | dot notation path***not really used |
picklistValues[] | List | Array of picklist values for enums |
precision | String | how precise is a value, $1.00 has precision of 2 |
primaryKey | Boolean | has this property if property is a primary key |
readOnly | Boolean | CE read only immutable operations |
reference | String | foreignKey of object |
relations | List | foreign key reference to other metadata? |
required | Boolean | CE required ** not usually used |
restrictedPicklist | Boolean | If enum is restricted (no other values other than picklist); or perhaps gross amount of values |
sampleValue | Object | sample data to put in payload |
subFormat | String | in general, don’t bother unless customer required |
type | String | type of object (https://cl.ly/11b77390824a) |
updateable | Boolean | can be updated, usually in PATCH or PUT |
vendorDisplayName | String | label seen in vendor UI |
vendorNativeType | String | Type in vendor system (nice to have) |
vendorPath | String | dot notation path |
vendorReadOnly | Boolean | vendor read only immutable operations |
vendorRequired | Boolean | use this for required fields |
Types and Formats
