Students who often write code in Python should have a feeling that Python's support for dictionaries is too comfortable, and it is basically as comfortable as writing Json in JS. However, because Python's support for Dict is relatively loose, it leads to a problem. If I have a function, if the parameter is a dictionary, the caller will go crazy. This is a situation; another common scenario It is parameter verification. Whether it is in the form of HTTP or RPC, many of our parameters are passed in the form of JSON. How to describe or verify this structure is a tricky problem.
For this issue of JSON, I have been paying attention to it for more than two years. I don't think I have seen a perfect way. I always have some regrets, but there are ways. For example, this article introduces a not bad However, the disadvantage is that the syntax is actually quite complicated. There is pain when formulating Schema, but it is very convenient and comfortable to use. This is a Python Library that I want to introduce in this article: JSON Schema .
Introduction to json schema
In fact, there is no need to introduce too much about json schema. It is nothing more than a library that defines json schema, which must contain two parts. The first part is the definition of Schama, which belongs to the document; the other part is the use of Schema, which belongs to development. aspects of the problem. This article starts from these two aspects and sees how JSON-Schema handles the schema of json.
Before talking about this python library, let's talk about some digressions by the way, that is the schema problem of json. When using the json-schema library, I was directed to a json-schema.org website, and then defined here about The relevant specification of json schema, the latest version is draft-7 , from this version, it seems that this is not the official version, but since there is a specification, and I scanned this specification for my needs, I found that it is quite Perfect, so, might as well use this specification for everyday use.
json schema definition
The json-schema library states in its description that it is currently fully supported: Draft3 and Draft4 specifications, so I will use Draft4 as the specification to describe the json schema here.
Let me talk about the example background I will use in this article. In this article, I will describe the model of a blog post , and then this blog post will belong to some categories . The categories are nested in the article . In fact, the category and the article are A many-to-many relationship, but because the classification itself is relatively simple, in order to simplify the model, I embedded the classification into the article model, so the overall model is like this:
According to this model, I can first define a simple corresponding json sequence:
Then we can use json-schema to define which Fields we have. Note that here we do not define other aspects to define, but just look at what Fields are needed, then a very simple Schema comes out. like this:
All elements are relatively complete, and the data structure of our post is simply and clearly explained. The next step is to define the type of each field.
json schema type
In the json schema, the description type is described in the form of KV, and the Key must be "type" , and then the value is the corresponding type. The corresponding type is not written casually, but can only be selected from the following 6 :
- "null"
- "boolean"
- "object"
- "array"
- "number"
- "string"
So we can populate our Schema first:
ok, it seems that this Schema has been a little effective now, but we may need to make more restrictions on some fields, such as status , we can't let others play at will, so naturally we need some ENUM values to choose, so also The following needs to be formulated.
json schema property
In the json schema, in addition to the type, some attributes can also be added to the field. The commonly used attributes are
- enum: enumerate some enumeration values, indicating that the field can only be one of the enumeration values, and the enumeration value must be a numeric value
- maxLength/minLength: the length limit of the string
- pattern: the pattern that the string must satisfy
Here are some restrictions on our schema:
It seems to be better, and then we looked at categories , and felt that this only specified the type as array, but did not say what type of elements in the array should be, so we still need to specify it.
json schema array
In json-schema, if you want to define the element type of an array, you can define it through the items attribute, and the way of defining it is the same as defining an object. Therefore, we can do this:
With this definition, our array schema is much more complete, but from here we can find that the classification model here is relatively simple, if it is more complex, then the Post 's schema is more ugly, is there any better one? way to simplify this schema.
json schema reference
In json-schema, we often have a situation where an Object contains another Object. In this case, of course, other Objects can be defined in the Object, but, as mentioned earlier, this is too complicated, so, in order to make it simpler Clearly describe the relationship, support reference in json-schema , use the keyword $ref in Object , and then the value is the definition of the corresponding Object, it should be noted that the definition of this Object needs to be in the definition of the same Object. value , an example is:
In this way, the Schema for Post is much clearer.
These are some common usages of json-schema, and the combination of these usages is enough for us to deal with most scenarios. If you encounter a scene that you can't handle, don't panic, you can go to the schema specification: json-schema , this specification is not complicated, and you can find what you need faster.
json schema validation
After we have defined the schema, it's time to try to use it in the code. I am still using the Python programming language here. I can't say that any programming language can be used here. According to some observations during my search, it seems that In addition to Python, there is also Java that I know it supports, but I don't know about other languages.
In Python, the first step is to install the dependent Library. It must be the old method. After pipinstalling , there is a simple way, why not use it:
$ pip install jsonschema
Then the use process is also extremely simple, the following is a verification code for the schema we have just now, you can always try it:
Then execute it again and see, the result must be:
$ json is ok!
Suppose we modify the json and see what happens when it is not ok? If you try, you will definitely find that the error "json is invalid!" will not be output, but an exception will be thrown directly, but the content of the exception is very detailed, and sometimes we don't need to know so much, so in order to Briefly, we need to understand validatethis function. Here is a brief look at the function prototype:
There are two types of exceptions that may be thrown here, namely:
- ValidationError
- ScheduleError
So we need to pay attention when doing development and debugging. If our Schema is written wrong, then no matter what json is verified, an exception will be thrown. This pit is worth noting. Then let's take a look at the content of the ValidationError exception:
It can be found that these two exceptions have the same properties, so we will print out their contents to see:
message: 'hello' is not one of ['PostStatus.PUBLISHED', 'PostStatus.DELETED', 'PostStatus.DRAFT']
path: deque(['status'])
cause: None
context: []
instance: hello
schema: {'enum': ['PostStatus.PUBLISHED', 'PostStatus.DELETED', 'PostStatus.DRAFT'], 'type': 'string'}
schema_path: deque(['properties', 'status', 'enum'])
parent: None
ok, so we can clearly understand the meaning of each field, and at the same time, we can use the corresponding fields according to our needs during development. In general, I recommend using message directly, so the final example code is modified into now:
Summarize
In this article, I tried to introduce the schema definition of json in a relatively simple way, at the same time, I also extended a simple example step by step, and finally used the Python programming language to verify the schema. The use of json is extremely common in daily development, and because of its good flexibility, it brings great convenience to our development; however, while enjoying the convenience, it often brings us unexpected bugs, Therefore, for some more important entrances and exits, you might as well add a Schema check to make the program run more robustly.