Readme #53
Readme #53
Conversation
|
should i make a separate readme file in the errorhandlers folder and link it with this readme file for explaination how we handle cases like anyOf or should make a separate docs folder in the project? |
|
I was thinking I was thinking something more like a docs folder at the top level. |
There was a problem hiding this comment.
A couple more small things to fix, then this is a good enough start.
A few more things I'd like to see in the next PR:
- Document the discriminator handling for anyOf
- Document the const/enum handling for anyOf
- Add examples for supporting custom keywords and error handlers
- Mention that we can reduce multiple instances of a keyword to a single message. (Example:
"allOf": [{ "minimum": 3 }, { "minimum": 5 }]only produces one message instead of one for each. - A separate documentation file (like anyOf.md) for any error handler that does something interesting like reduce multiple keywords into one message. Not every error handler needs a file, just the interesting ones.
.gitignore
Outdated
| @@ -1,6 +1,6 @@ | |||
| node_modules/ | |||
|
|
|||
| docs/ | |||
|
|
|||
There was a problem hiding this comment.
Ah, we can't put it in the docs folder because that's where typedoc generates its thing for the website. You'll need to come up with a different name. Maybe just documentation.
README.md
Outdated
| ## API Error Message Format | ||
|
|
||
| Our API Error Format includes :- | ||
| - **`schemaLocation`** - A JSON URI that points to the specific keyword(s) within the schema that failed validation. This can be a single string or an array of absolute keyword locations for errors that are grouped together. |
There was a problem hiding this comment.
A JSON URI isn't a thing. Maybe, "A URI with a JSON Pointer", or just "A URI" works too.
README.md
Outdated
|
|
||
| TODO: Write some examples | ||
| The library uses [fluent](https://projectfluent.org) `.ftl` files provide localized error messages. By default, only English is supported. |
There was a problem hiding this comment.
| The library uses [fluent](https://projectfluent.org) `.ftl` files provide localized error messages. By default, only English is supported. | |
| The library uses [fluent](https://projectfluent.org) `.ftl` files to provide localized error messages. By default, only English is supported. |
README.md
Outdated
| Sometimes a single validation issue is tied to **more than one schema keyword**. | ||
| For example, when both `minimum` and `exclusiveMinimum` apply, or when `minLength` and `maxLength` constraints overlap or when when both `minimum` and `maximum` apply. | ||
|
|
||
| Instead of generating duplicate error messages, It groups these into an **array of schema locations** and produces one concise, human-friendly message :- |
There was a problem hiding this comment.
They aren't really duplicate messages, right? How about,
| Instead of generating duplicate error messages, It groups these into an **array of schema locations** and produces one concise, human-friendly message :- | |
| Instead of multiple related error messages, It groups these into an **array of schema locations** and produces one concise, human-friendly message :- |
README.md
Outdated
| ### 4. Handling `anyOf` with Clarity | ||
|
|
||
| The `anyOf` keyword is a powerful but complex JSON Schema feature. **Better-JSON-Schema-Errors** intelligently simplifies its output by providing clear, consolidated error messages that are easier to debug. For detailed examples, see the dedicated [**anyOf** documentation](./docs/anyOf.md). |
There was a problem hiding this comment.
We should have several keywords with their own documentation file and I don't want to list each one of them individually. We should be able to describe some of the general strategies we use in the README and then link to the documentation directory as a whole for people to look through the individual documentation files.
I think here in the README we should talk about our general strategy of trying to determine which alternative the user intended and only showing those messages. Then the individual documentation can describe how we determine which alternative to choose.
We can add more anyOf cases once all cases will complete, and can add more example if you think if missing and can correct or include anything if missed.