{"id":1030,"library":"strictyaml","title":"StrictYAML","description":"StrictYAML is a type-safe YAML parser and validator for Python, focusing on a restricted, unambiguous subset of the YAML specification. It prioritizes a clear API, strict validation, human-readable exceptions, and the ability to round-trip (read, modify, and write) YAML while preserving comments. The current version is 1.7.3, with an active but irregular release cadence of patches and minor versions.","status":"active","version":"1.7.3","language":"python","source_language":"en","source_url":"https://github.com/crdoconnor/strictyaml","tags":["YAML","parser","validator","schema","configuration","type-safe","strict"],"install":[{"cmd":"pip install strictyaml","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Used for datetime parsing and validation within schemas.","package":"python-dateutil","optional":false}],"imports":[{"symbol":"load","correct":"from strictyaml import load"},{"symbol":"Map","correct":"from strictyaml import Map"},{"symbol":"Str","correct":"from strictyaml import Str"},{"symbol":"Int","correct":"from strictyaml import Int"},{"symbol":"Seq","correct":"from strictyaml import Seq"},{"symbol":"YAMLError","correct":"from strictyaml import YAMLError"}],"quickstart":{"code":"from strictyaml import load, Map, Str, Int, Seq, YAMLError\n\nyaml_snippet = \"\"\"\nname: Ford Prefect\nage: 42\npossessions:\n  - Towel\n  - 'No. 2 pencil'\n\"\"\"\n\n# Define a schema for validation and type casting\nschema = Map({\"name\": Str(), \"age\": Int(), \"possessions\": Seq(Str())})\n\ntry:\n    # Load YAML with the defined schema\n    document = load(yaml_snippet, schema)\n    print(\"Parsed data:\", document.data)\n    print(f\"Name (string): {document['name'].data}\")\n    print(f\"Age (int): {document['age'].data}\")\n    print(f\"First possession: {document['possessions'][0].data}\")\n\n    # Modify a value and output YAML (comments are preserved)\n    document['age'] = 43\n    print(\"\\nModified YAML:\\n\", document.as_yaml())\n\nexcept YAMLError as e:\n    print(f\"YAML Error: {e}\")\n\n# Example without a schema (all scalars are strings by default)\nyaml_no_schema = load(yaml_snippet)\nprint(\"\\nParsed without schema (age is string):\", yaml_no_schema.data['age'])","lang":"python","description":"This quickstart demonstrates how to parse a YAML string using a schema for type validation and casting, access parsed data, modify values, and handle potential YAMLError exceptions. It also shows the default behavior of parsing without a schema where all scalar values are treated as strings."},"warnings":[{"fix":"Access the `.data` attribute (e.g., `load(yaml_str, schema).data`) to retrieve the Python dict/list.","message":"In version 0.5, the default parse result of `load()` changed from directly returning a Python dict/list to returning a `YAML` object. To get the dict/list representation, users must now access the `.data` attribute of the returned object.","severity":"breaking","affected_versions":"<0.5"},{"fix":"Always define a `schema` using `strictyaml` validators (e.g., `Int()`, `Float()`, `Bool()`) if you require typed data beyond strings, lists, and dicts.","message":"StrictYAML intentionally refuses implicit typing (e.g., '42' is a string by default). Values are only type-cast according to an explicitly provided schema (e.g., `Int()`). This prevents common YAML surprises and security issues, but means it behaves differently from other YAML parsers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adhere to the StrictYAML subset of YAML. Avoid features like `!!str` explicit tags, `&anchor` references, and compact JSON-like syntax within your YAML files.","message":"StrictYAML parses only a restricted subset of the full YAML 1.2 specification. Features like duplicate keys, explicit tags, anchors/references, and flow-style YAML (embedded JSON) are intentionally disallowed or unsupported to enhance security and readability.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Read the content of your YAML file into a string first, then pass that string to `strictyaml.load()`. Example: `with open('config.yaml', 'r') as f: yaml_string = f.read(); doc = load(yaml_string, schema)`.","message":"StrictYAML, by design, only parses YAML from strings, not directly from file paths or file-like objects. This is a deliberate choice for explicitness and security.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Provide a schema (`strictyaml.load(yaml_str, schema)`) with appropriate validators (`Str()`, `Int()`, `Bool()`, `Datetime()`, etc.) to enable type conversion.","message":"When no schema is provided to `strictyaml.load()`, all scalar values (numbers, booleans, dates) are interpreted as strings. Automatic type inference, common in other YAML libraries, is disabled.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.7.3':54 'abil':37 'activ':57 'api':28 'cadenc':61 'clear':27 'comment':49 'configur':71 'current':51 'except':34 'focus':14 'human':32 'human-read':31 'irregular':59 'minor':65 'modifi':43 'parser':9,68 'patch':63 'preserv':48 'priorit':25 'python':13 'read':42 'readabl':33 'releas':60 'restrict':17 'round':40 'round-trip':39 'safe':7,74 'schema':70 'specif':23 'strict':29,75 'strictyaml':1,2 'subset':19 'trip':41 'type':6,73 'type-saf':5,72 'unambigu':18 'valid':11,30,69 'version':52,66 'write':45 'yaml':8,22,46,67","created_at":"2026-03-29T08:39:32.082798+00:00","updated_at":"2026-04-16T22:28:40.292798+00:00","problems":[{"fix":"Adjust the YAML content's structure or a specific value's type to conform to the defined schema, or modify the schema to accept the given YAML structure/type.\n\n```python\nfrom strictyaml import load, Map, Str\n\nyaml_string_correct = \"user_name: Alice\"\nschema = Map({\"user_name\": Str()})\nloaded_yaml = load(yaml_string_correct, schema)\n\n# Error case example:\n# yaml_string_error = \"user_name: {first: Alice, last: Smith}\"\n# loaded_yaml = load(yaml_string_error, schema) # This would raise the error\n```","cause":"The YAML document provides a mapping (object) where the StrictYAML schema expects a string, indicating a type mismatch during validation.","error":"MarkedYAMLError: Expected 'Str()' but got 'Map()'"},{"fix":"Ensure the key exists in the YAML document and is allowed by the schema. Use `get()` with a default value to handle optional keys safely, or define the key in the schema using `Optional()`.\n\n```python\nfrom strictyaml import load, Map, Str, Int, Optional\n\nyaml_string = \"name: Bob\\nage: 30\"\nschema = Map({\"name\": Str(), \"age\": Int(), Optional(\"email\"): Str()})\ndoc = load(yaml_string, schema)\n\n# Correct access:\nprint(doc[\"name\"].data)\n\n# Accessing an optional key safely:\nemail_node = doc.get(\"email\")\nif email_node:\n    print(email_node.data)\nelse:\n    print(\"Email not provided.\")\n\n# Error case example:\n# print(doc[\"phone\"].data) # Assuming 'phone' is not in schema or YAML\n```","cause":"An attempt was made to access a key within the parsed StrictYAML document that does not exist, either because it's missing from the YAML input or not defined in the schema.","error":"KeyError: 'non_existent_key' not found in document"},{"fix":"Correct the YAML syntax by ensuring that strings containing special characters are enclosed in single or double quotes, and that indentation and other YAML syntax rules are followed.\n\n```python\nfrom strictyaml import load, Map, Str\n\n# Corrected YAML: quoting a string with a colon\nyaml_string_correct = \"message: 'This contains a colon: and other stuff'\"\nschema = Map({\"message\": Str()})\nloaded_yaml = load(yaml_string_correct, schema)\n\n# Error case example (unquoted string with special characters):\n# yaml_string_error = \"message: This contains a colon: and other stuff\"\n# loaded_yaml = load(yaml_string_error, schema) # This would raise the error\n```","cause":"The input YAML string contains a scalar value that is not properly quoted or contains special characters (like a colon followed by a space) that require quoting, leading to a low-level parsing error.","error":"MarkedYAMLError: while scanning an unquoted scalar"},{"fix":"Always provide the YAML content as the first argument to the `strictyaml.load()` function.\n\n```python\nfrom strictyaml import load, Map, Str\n\n# Correct usage with yaml_string\nyaml_string = \"item: Apple\"\nschema = Map({\"item\": Str()})\ndoc = load(yaml_string, schema)\n\n# Error case example:\n# doc = load(schema=schema) # This would raise the TypeError\n```","cause":"The `strictyaml.load()` function was called without providing the necessary `yaml_string` argument, which is the YAML content to be parsed.","error":"TypeError: load() missing 1 required positional argument: 'yaml_string'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.7.3","cli_name":"","cli_version":null,"type":"library","homepage":"https://hitchdev.com/strictyaml","github":"https://github.com/crdoconnor/strictyaml","docs":"https://hitchdev.com/strictyaml/using","changelog":"https://hitchdev.com/strictyaml/changelog","pypi":"https://pypi.org/project/strictyaml/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}