Giters

datacontract / datacontract-specification

The Data Contract Specification Repository

Home Page:https://datacontract.com/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Change Examples Structure

jochenchrist opened this issue · comments

commented

The examples structure should be in line with models.

Current (v0.9.2):

examples:
  - type: csv # csv, json, yaml, custom
    model: orders
    data: |- # expressed as string or inline yaml or via "$ref: data.csv"
      order_id,order_timestamp,order_total
      "1001","2023-09-09T08:30:00Z",2500
      "1002","2023-09-08T15:45:00Z",1800
      "1003","2023-09-07T12:15:00Z",3200
      "1004","2023-09-06T19:20:00Z",1500
      "1005","2023-09-05T10:10:00Z",4200
      "1006","2023-09-04T14:55:00Z",2800
      "1007","2023-09-03T21:05:00Z",1900
      "1008","2023-09-02T17:40:00Z",3600
      "1009","2023-09-01T09:25:00Z",3100
      "1010","2023-08-31T22:50:00Z",2700
  - type: csv
    model: line_items
    data: |-
      lines_item_id,order_id,sku
      "1","1001","5901234123457"
      "2","1001","4001234567890"
      "3","1002","5901234123457"
      "4","1002","2001234567893"
      "5","1003","4001234567890"
      "6","1003","5001234567892"
      "7","1004","5901234123457"
      "8","1005","2001234567893"
      "9","1005","5001234567892"
      "10","1005","6001234567891"

Proposed:

examples:
  - type: csv # csv, json, yaml, custom
    orders: |- # expressed as string or inline yaml or via "$ref: data.csv"
      order_id,order_timestamp,order_total
      "1001","2023-09-09T08:30:00Z",2500
      "1002","2023-09-08T15:45:00Z",1800
      "1003","2023-09-07T12:15:00Z",3200
      "1004","2023-09-06T19:20:00Z",1500
      "1005","2023-09-05T10:10:00Z",4200
      "1006","2023-09-04T14:55:00Z",2800
      "1007","2023-09-03T21:05:00Z",1900
      "1008","2023-09-02T17:40:00Z",3600
      "1009","2023-09-01T09:25:00Z",3100
      "1010","2023-08-31T22:50:00Z",2700
    line_items: |-
      lines_item_id,order_id,sku
      "1","1001","5901234123457"
      "2","1001","4001234567890"
      "3","1002","5901234123457"
      "4","1002","2001234567893"
      "5","1003","4001234567890"
      "6","1003","5001234567892"
      "7","1004","5901234123457"
      "8","1005","2001234567893"
      "9","1005","5001234567892"
      "10","1005","6001234567891"
commented

Even simpler:

examples:
  orders: |-
    order_id,order_timestamp,order_total
    "1001","2023-09-09T08:30:00Z",2500
    "1002","2023-09-08T15:45:00Z",1800
    "1003","2023-09-07T12:15:00Z",3200
    "1004","2023-09-06T19:20:00Z",1500
    "1005","2023-09-05T10:10:00Z",4200
    "1006","2023-09-04T14:55:00Z",2800
    "1007","2023-09-03T21:05:00Z",1900
    "1008","2023-09-02T17:40:00Z",3600
    "1009","2023-09-01T09:25:00Z",3100
    "1010","2023-08-31T22:50:00Z",2700
  line_items: |-
    lines_item_id,order_id,sku
    "1","1001","5901234123457"
    "2","1001","4001234567890"
    "3","1002","5901234123457"
    "4","1002","2001234567893"
    "5","1003","4001234567890"
    "6","1003","5001234567892"
    "7","1004","5901234123457"
    "8","1005","2001234567893"
    "9","1005","5001234567892"
    "10","1005","6001234567891"
commented

Additional change:

type can be emitted, if one creates the examples inline:

examples:
  orders: 
    - order_id: "1001"
      order_timestamp: "2023-09-09T08:30:00Z"
      order_total: 2500
    - order_id: "1002"
      order_timestamp: "2023-09-08T15:45:00Z"
      order_total: 1800
  line_items: 
    - lines_item_id: "1"
      order_id: "1001"
      sku: "5901234123457"
commented

I would drop support for inline examples.
I have not seen any in real life.

This makes integration much easier.

commented

I think the JSON & CSV examples make sense - the inline I think people might find more confusing