Skip to content

Commit

Permalink
Update the "Best practices" list
Browse files Browse the repository at this point in the history
It replaces the list in "Constraints and errors". That section now points to
"Best practices".
  • Loading branch information
ssilverman committed Sep 13, 2020
1 parent 9256564 commit e61c615
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 24 deletions.
3 changes: 2 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ and this project adheres to
* Added a version and "schemas" path section to the schema $id.
* Added an "Open questions" top-level section to the README.
* Added a "Best practices" top-level section to the README that describes how to
avoid creating ill-defined messages.
avoid creating ill-defined messages. This replaces the list from the
"Constraints and errors" section.

### Changed
* Capitalized titles in the schema.
Expand Down
38 changes: 15 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,22 +130,10 @@ should set appropriate values for the `"maxLength"` field for strings and the

### Constraints and errors

The schema does not capture every possible error. Some errors can only be caught
after processing a schema instance. It is an error if any of the requirements
below are not met.

1. `"bitField"` type: the number of bits defined in the array must be less than
or equal to the `"size"` value.
2. `"bytes"` type: the `"minLength"` value must be less than or equal to the
`"maxLength"` value.
3. `"string"` type: any size limits described by `"pattern"` must not contradict
the limits described by `"minLength"` and `"maxLength"`. As well, the
`"minLength"` value must be less than or equal to the `"maxLength"` value.
4. If a command is a duplicate of another command then it cannot duplicate
itself. For example, a `"get_response"` cannot have a value
of `"get_response"`.
5. `"refType"`: the reference must point to an object having one of the types in
`#/$defs/oneOfTypes` and there must not be any circular references.
Note that the schema does not capture every possible error. Some errors can only
be caught after processing a schema instance. Please see the
[Best practices](#best-practices) section for more details about avoiding these
kinds of errors.

## Best practices

Expand All @@ -161,15 +149,19 @@ of problems.
that a responder doesn't need this, but many responders do because they're
implemented on smaller systems that may need to preallocate memory.
2. Minimums should be less than maximums. For example, the "bytes" type has
`"minLength"` and `"maxLength"` fields. `"minLength"` should be less than or
`"minLength"` and `"maxLength"` fields; `"minLength"` should be less than or
equal to `"maxLength"`.
3. Bit field sizes should match the number of defined bits.
4. A command should not refer to itself. Please refer to the "Command Duplicate"
3. A bit field size should be greater than or equal to the number of its
defined bits.
4. A command should not refer to itself. For example, a `"get_response"` cannot
have a value of `"get_response"`. Please refer to the "Command Duplicate"
subschema under the "command" schema.
5. References ("$ref") should refer to a valid object. Also, there should not be
any circular references.
6. String patterns should not contradict any minimum or maximum lengths, if
either are provided.
5. References ("$ref") should refer to an object having a valid type. Also,
there should not be any circular references.
6. String patterns should not contradict any minimum or maximum lengths, and
vice versa.
7. The `"format"` value for bytes or strings, if a fixed-size type, should not
contradict any minimum or maximum lengths.

## Open questions

Expand Down

0 comments on commit e61c615

Please sign in to comment.