schema_validator.py 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540
  1. # Copyright 2018 The Chromium Authors. All rights reserved.
  2. # Use of this source code is governed by a BSD-style license that can be
  3. # found in the LICENSE file.
  4. import re
  5. # Dict with valid schema type names as keys. The values are the allowed
  6. # attribute names and their expected value types.
  7. #
  8. # These are the ONLY supported schema features. For the full schema proposal see
  9. # https://json-schema.org/understanding-json-schema/index.html.
  10. #
  11. # There are also these departures from the proposal:
  12. # - "additionalProperties": false is not supported. Instead, it is assumed by
  13. # default. The value of "additionalProperties" has to be a schema.
  14. ALLOWED_ATTRIBUTES_AND_TYPES = {
  15. 'boolean': {
  16. 'type': str, # required
  17. 'id': str, # optional
  18. 'description': str, # optional
  19. 'sensitiveValue': bool # optional
  20. },
  21. 'string': {
  22. 'type': str, # required
  23. 'id': str, # optional
  24. 'description': str, # optional
  25. 'enum': list, # optional
  26. 'pattern': str, # optional
  27. 'sensitiveValue': bool # optional
  28. },
  29. 'integer': {
  30. 'type': str, # required
  31. 'id': str, # optional
  32. 'description': str, # optional
  33. 'enum': list, # optional
  34. 'minimum': int, # optional
  35. 'maximum': int, # optional
  36. 'sensitiveValue': bool # optional
  37. },
  38. 'array': {
  39. 'type': str, # required
  40. 'id': str, # optional
  41. 'items': dict, # required,
  42. 'description': str, # optional
  43. 'sensitiveValue': bool # optional
  44. },
  45. 'object': {
  46. 'type': str, # required
  47. 'id': str, # optional
  48. 'description': str, # optional
  49. 'properties': dict, # one of these 3 properties is required
  50. 'patternProperties': dict, # one of these 3 properties is required
  51. 'additionalProperties': dict, # one of these 3 properties is required
  52. 'required': list, # optional
  53. 'sensitiveValue': bool # optional
  54. }
  55. }
  56. # Dict of allowed attributes and their expected types for schemas with a $ref.
  57. ALLOWED_REF_ATTRIBUTES_AND_TYPES = {'$ref': str, 'description': str}
  58. # Dict of human-readable enum types and their python types as values.
  59. ENUM_ITEM_TYPES = {'integer': int, 'string': str}
  60. class SchemaValidator(object):
  61. """This class can validate schemas by calling ValidateSchema() or can
  62. validate values against their schema by calling ValidateValue().
  63. Schemas with an 'id' used as $ref link by another schema have to be passed to
  64. ValidateSchema() before the schema with the $ref can be used in
  65. ValidateSchema() or ValidateValue().
  66. |schemas_by_id| is used as storage for schemas with their 'id' as key and
  67. their schemas as value.
  68. """
  69. def __init__(self):
  70. self.schemas_by_id = {}
  71. self.invalid_ref_ids = set()
  72. self.found_ref_ids = set()
  73. self.errors = []
  74. self.enforce_use_entire_schema = False
  75. self.expected_properties = {}
  76. self.expected_pattern_properties = {}
  77. self.expected_additional_properties = {}
  78. self.used_properties = {}
  79. self.used_pattern_properties = {}
  80. self.used_additional_properties = {}
  81. def ValidateSchema(self, schema):
  82. """Checks if |schema| is a valid schema and only uses valid $ref links.
  83. See _ValidateSchemaInternal() for a detailed description of the schema
  84. validation. This method also checks if all used $ref links are known and
  85. valid.
  86. Args:
  87. schema (dict): The JSON schema.
  88. Returns:
  89. A list contains all schema errors.
  90. """
  91. self.found_ref_ids.clear()
  92. self.errors = []
  93. self._ValidateSchemaInternal(schema)
  94. unknown_ref_ids = self.found_ref_ids.difference(self.schemas_by_id.keys())
  95. for unknown_ref_id in unknown_ref_ids:
  96. if unknown_ref_id in self.invalid_ref_ids:
  97. self._Error("$ref to invalid schema '%s'." % unknown_ref_id)
  98. else:
  99. self._Error("Unknown $ref '%s'." % unknown_ref_id)
  100. return self.errors
  101. def _ValidateSchemaInternal(self, schema):
  102. """Check if |schema| is a valid schema.
  103. This method checks whether |schema| is a dict, has a valid 'type' property,
  104. only has properties and values allowed by its type (see
  105. ALLOWED_ATTRIBUTES_AND_TYPES) and calls the appropriate
  106. _Validate{Integer,String,Array,Object}Schema() method.
  107. If the schema has a $ref, the $ref id is added to |found_ref_ids| so that
  108. its existence can be validated later on in ValidateSchema(). They may
  109. also not contain other attributes except for '$ref' and 'description' (see
  110. ALLOWED_REF_ATTRIBUTES_AND_TYPES).
  111. If the schema has an id, the id has to be unique and the schema is stored
  112. for later re-use if it is valid.
  113. Args:
  114. schema (dict): The JSON schema.
  115. """
  116. num_errors_before = len(self.errors)
  117. # Check that schema is of type dict.
  118. if not isinstance(schema, dict):
  119. self._Error("Schema must be a dict.")
  120. # Validate $ref links. All '$ref' links are gathered in |found_ref_links| so
  121. # that their existence can be validated later on in ValidateSchema(schema).
  122. if '$ref' in schema:
  123. ref_id = schema['$ref']
  124. for name, value in schema.items():
  125. if name not in ALLOWED_REF_ATTRIBUTES_AND_TYPES:
  126. self._Error("Attribute '%s' is not allowed for schema with $ref '%s'."
  127. % (name, ref_id))
  128. expected_type = ALLOWED_REF_ATTRIBUTES_AND_TYPES[name]
  129. if not isinstance(value, expected_type):
  130. self._Error(
  131. ("Attribute value for '%s' (%s) has incorrect type (Expected "
  132. "type: '%s'; actual type: '%s')") % (name, value, expected_type,
  133. type(value)))
  134. self.found_ref_ids.add(ref_id)
  135. return
  136. # Every schema (non-ref) must have a type.
  137. if 'type' not in schema:
  138. self._Error("Missing attribute 'type'.")
  139. schema_type = schema['type']
  140. # Check that the type is valid.
  141. if schema_type not in ALLOWED_ATTRIBUTES_AND_TYPES:
  142. self._Error("Unknown type: %s" % schema_type)
  143. # Check that each schema only contains attributes that are allowed in their
  144. # respective type and that their values are of correct type.
  145. allowed_attributes = ALLOWED_ATTRIBUTES_AND_TYPES[schema_type]
  146. for attribute_name, attribute_value in schema.items():
  147. if attribute_name in allowed_attributes:
  148. expected_type = allowed_attributes[attribute_name]
  149. if not isinstance(attribute_value, expected_type):
  150. self._Error(
  151. ("Attribute '%s' has incorrect type (Expected type: '%s'; actual "
  152. "type: '%s').") % (attribute_name, expected_type,
  153. type(attribute_value)))
  154. else:
  155. self._Error("Attribute '%s' is not allowed for type '%s'." %
  156. (attribute_name, schema_type))
  157. # Validate schemas depending on 'type'.
  158. if schema_type == 'string':
  159. self._ValidateStringSchema(schema)
  160. elif schema_type == 'integer':
  161. self._ValidateIntegerSchema(schema)
  162. elif schema_type == 'array':
  163. self._ValidateArraySchema(schema)
  164. elif schema_type == 'object':
  165. self._ValidateObjectSchema(schema)
  166. # If the schema has an 'id', ensure that the id is unique and store the
  167. # schema for later reference.
  168. if 'id' in schema:
  169. ref_id = schema['id']
  170. if ref_id in self.schemas_by_id:
  171. self._Error("ID '%s' is not unique." % ref_id)
  172. if len(self.errors) == num_errors_before:
  173. self.schemas_by_id[ref_id] = schema
  174. else:
  175. self.invalid_ref_ids.add(ref_id)
  176. def _ValidateStringSchema(self, schema):
  177. """Validates a |schema| with type 'string'.
  178. Validates the 'enum' (see _ValidateEnum()) and/or 'pattern' property (see
  179. _ValidatePattern()) if existing.
  180. Args:
  181. schema (dict): The JSON schema.
  182. """
  183. if 'enum' in schema:
  184. self._ValidateEnum(schema['enum'], 'string')
  185. if 'pattern' in schema:
  186. self._ValidatePattern(schema['pattern'])
  187. def _ValidateIntegerSchema(self, schema):
  188. """Validates a |schema| with type 'integer'.
  189. Validates the 'enum' property (see _ValidateEnum()) if existing. This
  190. method also ensures that the specified minimum value is smaller or equal to
  191. the specified maximum value, if both exist.
  192. Args:
  193. schema (dict): The JSON schema.
  194. """
  195. if 'enum' in schema:
  196. self._ValidateEnum(schema['enum'], 'integer')
  197. if ('minimum' in schema and 'maximum' in schema and
  198. schema['minimum'] > schema['maximum']):
  199. self._Error("Invalid range specified: [%s; %s]" % (schema['minimum'],
  200. schema['maximum']))
  201. def _ValidateArraySchema(self, schema):
  202. """Validates a |schema| with type 'array'.
  203. Validates that the 'items' attribute exists and its value is a valid schema.
  204. Args:
  205. schema (dict): The JSON schema.
  206. """
  207. if 'items' in schema:
  208. self._ValidateSchemaInternal(schema['items'])
  209. else:
  210. self._Error("Schema of type 'array' must have an 'items' attribute.")
  211. def _ValidateObjectSchema(self, schema):
  212. """Validates a schema of type 'object'.
  213. If |schema| has a 'required' attribute, this method validates that it is not
  214. empty, only contains strings and only contains property names of properties
  215. defined in the 'properties' attribute.
  216. This method also ensures that at least one of 'properties',
  217. 'patternProperties' or 'additionalProperties' is defined.
  218. If 'properties' are defined, they must have non-empty string names and
  219. contain a valid schema.
  220. If 'patternProperties' are defined, they must be valid regex patterns and
  221. contain a valid schema.
  222. If 'additionalProperties is defined, it must contain a valid schema.
  223. Args:
  224. schema (dict): The JSON schema.
  225. '"""
  226. # Validate 'required' attribute.
  227. if 'required' in schema:
  228. required_properties = schema['required']
  229. if not required_properties:
  230. self._Error("Attribute 'required' may not be empty (omit it if empty).")
  231. if not all(
  232. isinstance(required_property, str)
  233. for required_property in required_properties):
  234. self._Error("Attribute 'required' may only contain strings.")
  235. properties = schema.get('properties', {})
  236. unknown_properties = [
  237. property_name for property_name in required_properties
  238. if property_name not in properties
  239. ]
  240. if unknown_properties:
  241. self._Error("Unknown properties in 'required': %s" % unknown_properties)
  242. # Validate '*properties' attributes.
  243. has_any_properties = False
  244. if 'properties' in schema:
  245. has_any_properties = True
  246. properties = schema['properties']
  247. for property_name, property_schema in properties.items():
  248. if not isinstance(property_name, str):
  249. self._Error("Property name must be a string.")
  250. if not property_name:
  251. self._Error("Property name may not be empty.")
  252. self._ValidateSchemaInternal(property_schema)
  253. if 'patternProperties' in schema:
  254. has_any_properties = True
  255. pattern_properties = schema['patternProperties']
  256. for property_pattern, property_schema in pattern_properties.items():
  257. self._ValidatePattern(property_pattern)
  258. self._ValidateSchemaInternal(property_schema)
  259. if 'additionalProperties' in schema:
  260. has_any_properties = True
  261. additional_properties = schema['additionalProperties']
  262. self._ValidateSchemaInternal(additional_properties)
  263. if not has_any_properties:
  264. self._Error(
  265. "Schema of type 'object' must have at least one of the following "
  266. "attributes: ['properties', 'patternProperties' or "
  267. "'additionalProperties'].")
  268. def _ValidateEnum(self, enum, schema_type):
  269. """Validates an |enum| of type |schema_type|.
  270. Validates that |enum| is not empty and its elements have the correct type
  271. according to |schema_type| (see ENUM_ITEM_TYPES).
  272. Args:
  273. enum (list): The list of enum values.
  274. schema_type (str): The schema type in which the enum is used.
  275. """
  276. if not enum:
  277. self._Error("Attribute 'enum' may not be empty.")
  278. item_type = ENUM_ITEM_TYPES[schema_type]
  279. if not all(isinstance(enum_value, item_type) for enum_value in enum):
  280. self._Error(("Attribute 'enum' for type '%s' may only contain elements of"
  281. " type %s: %s") % (schema_type, item_type, enum))
  282. def _ValidatePattern(self, pattern):
  283. """Validates a regex |pattern|.
  284. Validates that |pattern| is a string and can be used as regex pattern.
  285. Args:
  286. pattern (str): The regex pattern.
  287. """
  288. if not isinstance(pattern, str):
  289. self._Error("Pattern must be a string: %s" % pattern)
  290. try:
  291. re.compile(pattern)
  292. except re.error:
  293. self._Error("Pattern is not a valid regex: %s" % pattern)
  294. def ValidateValue(self, schema, value, enforce_use_entire_schema=False):
  295. """Validates that |value| complies to |schema|.
  296. See _ValidateValueInternal(schema, value) for a detailed description of the
  297. value validation. If |enforce_use_entire_schema| is enabled, each value and
  298. its sub-values have to use every property of each used schema at least once
  299. and values with schema type 'array' may not be empty.
  300. Args:
  301. schema (dict): The JSON schema.
  302. value (any): The value being validated.
  303. enforce_use_entire_schema (bool): Whether each property hsa to be used at
  304. least once.
  305. Returns:
  306. A list contains all value errors.
  307. """
  308. self.enforce_use_entire_schema = enforce_use_entire_schema
  309. self.expected_properties = {}
  310. self.expected_pattern_properties = {}
  311. self.expected_additional_properties = {}
  312. self.used_properties = {}
  313. self.used_pattern_properties = {}
  314. self.used_additional_properties = {}
  315. self.errors = []
  316. self._ValidateValueInternal(schema, value)
  317. # Check that all properties, patternProperties and additionalProperties were
  318. # used at least once for each schema.
  319. if self.enforce_use_entire_schema:
  320. if self.expected_properties != self.used_properties:
  321. for schema_id, expected_properties \
  322. in self.expected_properties.items():
  323. used_properties = self.used_properties.get(schema_id, set())
  324. unused_properties = expected_properties.difference(used_properties)
  325. if unused_properties:
  326. self._Error("Unused properties: %s" % unused_properties)
  327. if self.expected_pattern_properties != self.used_pattern_properties:
  328. for schema_id, expected_properties \
  329. in self.expected_pattern_properties.items():
  330. used_properties = self.used_pattern_properties.get(schema_id, set())
  331. unused_properties = expected_properties.difference(used_properties)
  332. if unused_properties:
  333. self._Error("Unused pattern properties: %s" % unused_properties)
  334. if self.expected_additional_properties != self.used_additional_properties:
  335. self._Error("Unused additional properties.")
  336. return self.errors
  337. def _ValidateValueInternal(self, schema, value):
  338. """Validates that |value| complies to |schema|.
  339. This method checks if the |value|'s type is correct according to type
  340. expected in |schema| and calls the associated
  341. _Validate{Integer,String,Array,Object}ValueInternal(schema, value).
  342. Args:
  343. schema (dict): The JSON schema.
  344. value (any): The value being validated.
  345. """
  346. # Load schema from store if it has '$ref'.
  347. if '$ref' in schema:
  348. ref_id = schema['$ref']
  349. if ref_id not in self.schemas_by_id:
  350. self._Error("Unknown $ref id: %s" % ref_id)
  351. schema = self.schemas_by_id[ref_id]
  352. schema_type = schema.get('type')
  353. if schema_type == 'boolean' and isinstance(value, bool):
  354. pass # Boolean doesn't need any validation.
  355. elif schema_type == 'integer' and isinstance(value, int):
  356. self.ValidateIntegerValue(schema, value)
  357. elif schema_type == 'string' and isinstance(value, (bytes, str)):
  358. self.ValidateStringValue(schema, value)
  359. elif schema_type == 'array' and isinstance(value, list):
  360. self.ValidateArrayValue(schema, value)
  361. elif schema_type == 'object' and isinstance(value, dict):
  362. self.ValidateObjectValue(schema, value)
  363. else:
  364. # Type mismatch or unknown type.
  365. self._Error(
  366. "Type mismatch or unknown (schema_type: %s; value_type: %s): %s" %
  367. (schema_type, type(value), value))
  368. def ValidateIntegerValue(self, schema, value):
  369. """Validates an integer |value| according to |schema|.
  370. If the |schema| has an enum of possible values, check whether |value| is one
  371. of them.
  372. If 'minimum' and/or 'maximum' are defined in |schema|, check that
  373. minimum <= value <= maximum.
  374. Args:
  375. schema (dict): The JSON schema.
  376. value (int): The value being validated.
  377. """
  378. if 'enum' in schema:
  379. self._ValidateEnumValue(schema['enum'], value)
  380. if (('minimum' in schema and value < schema['minimum']) or
  381. ('maximum' in schema and value > schema['maximum'])):
  382. self._Error(
  383. "Value %s not in range [%s,%s]." %
  384. (value, schema.get('minimum', '-inf'), schema.get('maximum', '+inf')))
  385. def ValidateStringValue(self, schema, value):
  386. """Validates a string |value| according to |schema|.
  387. If the |schema| has an enum of possible values, check whether |value| is one
  388. of them.
  389. If the |schema| has a 'pattern' attribute, check whether |value| matches the
  390. pattern.
  391. Args:
  392. schema (dict): The JSON schema.
  393. value (str): The value being validated.
  394. """
  395. if 'enum' in schema:
  396. self._ValidateEnumValue(schema['enum'], value)
  397. if 'pattern' in schema:
  398. pattern = schema['pattern']
  399. if not re.search(pattern, value):
  400. self._Error(
  401. "String value '%s' does not match pattern '%s'." % (value, pattern))
  402. def ValidateArrayValue(self, schema, child_values):
  403. """Validates an array |child_values| according to |schema|.
  404. Validates each item in |child_values| (see _ValidateValueInternal()).
  405. If |enforce_use_entire_schema| is enabled, the value must contain at least
  406. one element.
  407. Args:
  408. schema (dict): The JSON schema.
  409. child_values (list): The list of children being validated.
  410. """
  411. child_schema = schema.get('items')
  412. for child_value in child_values:
  413. self._ValidateValueInternal(child_schema, child_value)
  414. if self.enforce_use_entire_schema and not child_values:
  415. self._Error("Array must contain at least one item.")
  416. def ValidateObjectValue(self, schema, value):
  417. """Validates an object |value| according to |schema|.
  418. Validates each property in |value| according to its matching schema out of
  419. the |schema|'s 'properties', 'patternProperties' or 'additionalProperties'
  420. properties. Also adds the property to the set of |used_*properties|.
  421. If the |schema| is used for the first time in this validation, the
  422. |expected_*properties| are initialized to the |schema|'s properties.
  423. Args:
  424. schema (dict): The JSON schema.
  425. value (dict): The value being validated.
  426. """
  427. # Get allowed properties.
  428. properties = schema.get('properties', {})
  429. pattern_properties = schema.get('patternProperties', {})
  430. additional_properties = schema.get('additionalProperties', {})
  431. # If the schema hasn't been used before, store sets of expected properties,
  432. # patternProperties and a bool whether we expect additionalProperties to be
  433. # used. Also initialize the list of used properties and patternProperties to
  434. # empty sets.
  435. schema_id = id(schema)
  436. if schema_id not in self.expected_properties:
  437. self.expected_properties[schema_id] = set(properties.keys())
  438. self.expected_pattern_properties[schema_id] = set(
  439. pattern_properties.keys())
  440. self.expected_additional_properties[schema_id] = (
  441. 'additionalProperties' in schema)
  442. self.used_properties[schema_id] = set()
  443. self.used_pattern_properties[schema_id] = set()
  444. self.used_additional_properties[schema_id] = False
  445. for property_key, property_value in value.items():
  446. # Find property schema from either properties, patternProperties or
  447. # additionalProperties.
  448. property_schema = {}
  449. if properties and property_key in properties:
  450. property_schema = properties[property_key]
  451. self.used_properties[schema_id].add(property_key)
  452. elif pattern_properties:
  453. matched_pattern = next((pattern
  454. for pattern in pattern_properties.keys()
  455. if re.search(pattern, property_key)), "")
  456. property_schema = pattern_properties.get(matched_pattern, {})
  457. self.used_pattern_properties[schema_id].add(matched_pattern)
  458. if not property_schema and additional_properties:
  459. property_schema = additional_properties
  460. self.used_additional_properties[schema_id] = True
  461. if not property_schema:
  462. self._Error("Unknown property: %s" % property_key)
  463. self._ValidateValueInternal(property_schema, property_value)
  464. # Check that all 'required' properties are existing.
  465. if 'required' in schema:
  466. missing_required = [
  467. required_key for required_key in schema['required']
  468. if required_key not in value
  469. ]
  470. if missing_required:
  471. self._Error("Required property missing: %s" % missing_required)
  472. def _ValidateEnumValue(self, enum, value):
  473. """Validates that |value| is in |enum|.
  474. Args:
  475. enum (list): The list of allowed values.
  476. value (any): The value being validated.
  477. """
  478. if value not in enum:
  479. self._Error("Unknown enum value: %s (expected one of %s)" % (value, enum))
  480. def _Error(self, message):
  481. """Captures an error.
  482. Stores error |messages|.
  483. Args:
  484. message (str): The error message."""
  485. self.errors.append(message)