api-definitions/replay-rules.yaml at main · Rebilly/api-definitions · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
extends:
    - recommended-strict
# TODO: add necessary rules for the Replay Platform API.
#  - enforce a rule so that you cannot add inline schema into responses.
rules:
  rule/multi-sentence-descriptions-must-use-block-scalars:
    severity: error
    subject:
      type: any
      property: description
    message: |-
      Multi-sentence descriptions must use block scalars with semantic line breaks. For more information, see [Redocly documentation](../website/api-definitions/WRITING-STYLE.md).
    where:
      - subject:
          type: any
          property: description
        assertions:
          defined: true
          minLength: 1
          # Exclude descriptions that already contain newlines (block scalars)
          notPattern: /\n/
    assertions:
      # period + spaces (not newline) + Uppercase => inline multi-sentence
      notPattern: /\.(?!\r?\n)[ ]+[A-Z]/

  rule/descriptions-must-not-start-with-articles:
    severity: warn
    subject:
      type: Schema
      property: description
    message: |-
      Description must not start with 'The' or 'A'
      For more information, see [Redocly documentation](../website/api-definitions/WRITING-STYLE.md).
    where:
      - subject:
          type: Schema
          property: description
        assertions:
          defined: true
          minLength: 1
    assertions:
      notPattern: /^(The|A)\s/

  rule/id-fields-must-have-meaningful-context:
    severity: warn
    subject:
      type: Schema
      property: description
    message: |-
      ID fields must provide meaningful context,
      and not just repeat the field name.
      For more information, see [Writing style](../website/api-definitions/WRITING-STYLE.md).
    where:
      - subject:
          type: Schema
          property: description
        assertions:
          defined: true
          minLength: 1
      - subject:
          type: Schema
          property: name
        assertions:
          defined: true
          pattern: /[Ii]d$/
    assertions:
      # Check if description is just repeating the field name
      notPattern: /^(The\s+)?[Ii]d\s+(of\s+)?(the\s+)?(item|field|object|value)\.?$/

  rule/timestamp-fields-must-start-correctly:
    severity: error
    subject:
      type: Schema
      property: description
    message: |-
      Timestamp fields must start with 'Date and time when'
      For more information, see [Writing style](../website/api-definitions/WRITING-STYLE.md#timestamp-fields).
    where:
      - subject:
          type: Schema
          property: description
        assertions:
          defined: true
          minLength: 1
      - subject:
          type: Schema
          property: format
        assertions:
          defined: true
          pattern: /date-time/
      - subject:
          type: Schema
          property: description
        assertions:
          notPattern: /^Default value\.$/
    assertions:
      pattern: /^Date and time when/

  rule/boolean-fields-must-start-correctly:
    severity: error
    subject:
      type: Schema
      property: description
    message: |-
      Boolean fields must start with 'Specifies if'
      For more information, see [Writing style](../website/api-definitions/WRITING-STYLE.md#boolean-fields).
    where:
      - subject:
          type: Schema
          property: description
        assertions:
          defined: true
          minLength: 1
      - subject:
          type: Schema
          property: type
        assertions:
          defined: true
          pattern: /boolean/
      - subject:
          type: Schema
          property: description
        assertions:
          notPattern: /^Default value\.$/
    assertions:
      pattern: /^Specifies if/

  rule/summaries-must-not-end-with-period:
    severity: error
    subject:
      type: any
      property: summary
    message: |-
      Summary fields must not end with a period.
      For more information, see [Writing style](../website/api-definitions/WRITING-STYLE.md#summaries).
    where:
      - subject:
          type: any
          property: summary
        assertions:
          defined: true
          minLength: 1
    assertions:
      notPattern: /\.$/

  rule/descriptions-must-not-use-possessive-apostrophes:
    severity: error
    subject:
      type: any
      property: description
    message: |-
      Descriptions must not use possessive apostrophes ('s) for inanimate objects.
      Use prepositions instead.
      Example: "invoice for a subscription" not "subscription's invoice".
      For more information, see [Writing style](../website/api-definitions/WRITING-STYLE.md#possessive-apostrophes).
    where:
      - subject:
          type: any
          property: description
        assertions:
          defined: true
          minLength: 1
    assertions:
      # Match possessive apostrophes for inanimate objects
      # Pattern matches: word's, WORD's, acronym's, etc.
      # Excludes: customer's, player's, merchant's (animate objects)
      notPattern: /\b(?!customer|player|merchant|contact|user|individual|person)\w+'s\b/i