Requirements for Ingestion API Schema File

Use the Ingestion API Schema File requirements to successfully build a file to bring data into Data 360.

To create an ingestion API source in Data 360, the schema file you upload must meet specific requirements.

Uploaded schemas have to be in valid OpenAPI format with a .yml or .yaml extension. OpenAPI version 3.0.x is supported
Objects can’t have nested objects.
Each schema must have at least 1 object. Each object must have at least 1 field.
Only one Data Stream can be created per object per connection.
Objects can’t have more than 1000 fields.
Objects can’t be longer than 79 characters.
Field names can’t exceed 39 characters.
Object names must contain only a-z, A-Z, 0-9, _, and -. Unicode characters aren’t supported.
Objects can’t be deleted from the schema after they are uploaded.
Field names must contain only a-z, A-Z, 0-9, _, and -. Unicode characters aren’t supported.
Field names can’t be any of these reserved words: date_id, location_id, dat_account_currency, dat_exchange_rate, pacing_period, pacing_end_date, row_count, version. Field names can’t contain string __.
A field once added to an object’s schema can’t be removed. Similarly, an object once added to the top-level schema associated with an active connection can’t be removed.

Fields meet the type and format requirements:

For boolean type

1booleanField:
2            type: boolean

For date type

1dateField:
2            type: string
3            format: date

For datetime type
1dateTimeField: 2 type: string 3 format: date-time
Once the data is ingested, the date and time values are adjusted as per the time zone configured in your org.
Note

For email type

1emailField:
2            type: string
3            format: email

For number type
1numberField: 2 type: number

For phone type

1phoneField:
2            type: string
3            format: phone

For percent type

1percentField:
2            type: string
3            format: percent

For text type
1textField: 2 type: string

For URL type

1urlField:
2            type: string
3            format: url

Object names can’t be duplicated, case insensitive.
Objects can’t have duplicate field names, case insensitive.
Date data type fields in your payloads must be valid calendar dates conforming to ISO 8601 format yyyy-MM-dd.
DateTime data type fields in your payloads must be in ISO 8601 UTC Zulu with format yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

When updating your schema, be aware:

Existing field data types can’t be changed.
Upon updating an object, all of the existing fields for that object must be present.
Your updated schema file only includes changed objects, so you don’t have to provide a comprehensive list of objects each time.
A datetime field must be present for objects that are intended forengagementcategory. Objects of category profile or other don’t impose this same requirement.

If you send a payload using field API names instead of the schema-defined field names, the system can’t recognize the fields or their values. As a result, the data stream displays a single row with blank columns. Since the payload has no valid fields, the ingestion process interprets each call as an upsert to the same record, ultimately populating that record with only blank values.

Note

Example

Ingestion API schemas have set requirements. Review the schema requirements before ingestion.

Schema example:

1openapi: 3.0.3
2components:
3  schemas:
4    Order:
5      type: object
6      properties:
7        contact_name:
8          type: string
9        created_date:
10          type: string
11          format: date-time
12        id:
13          type: string
14        total:
15          type: number
16        shipAddress:
17          type: string
18        taxExempt:
19          type: string
20        tax_rate:
21          type: number
22        my_email:
23          type: string
24          format: email
25        my_phone:
26          type: string
27          format: phone
28        my_url:
29          type: string
30          format: url
31        my_percent:
32          type: string
33          format: percent
34        is_new:
35          type: boolean
36        modifie_date:
37          type: string
38          format: date-time
39    OrderItem:
40      type: object
41      properties:
42        cost:
43          type: number
44        createdDate:
45          type: string
46          format: date-time
47        quantity:
48          type: number
49        name:
50          type: string
51        orderId:
52          type: string
53        itemNumber:
54          type: number
55    SalesCustomer:
56      type: object
57      properties:
58        address:
59          type: string
60        age:
61          type: number
62        city:
63          type: string
64        country:
65          type: string
66        modifiedDate:
67          type: string
68          format: date-time
69        firstName:
70          type: string
71        gender:
72          type: string
73        id:
74          type: string
75        lastName:
76          type: string
77        createdDate:
78          type: string
79          format: date-time