Software Design Document

jsonparser v

This document was auto-generated by ReqProof on 2026-08-27 11:40:54 UTC. Do not edit manually; regenerate from source requirements and design data.

Table of Contents

1. Introduction

1.1 Purpose

This Software Design Document (SDD) describes the architecture and detailed design of jsonparser. It provides the technical design decisions, component decomposition, interface contracts, data structures, and traceability needed to satisfy safety-critical software development standards.

1.2 Scope

1
Components
123
Requirements
242
Variables
0
Interfaces

1.3 Definitions and Acronyms

TermDefinition
SDDSoftware Design Document
SRSSoftware Requirements Specification
SYS-REQSystem-level requirement
FRETishFormal requirements language based on NASA FRET
LTLLinear Temporal Logic
CoCoSpecContract-based specification language for Lustre model checkers
MermaidDiagram-as-code rendering library

1.4 Standards Compliance

IEC 62304 Clause 5.3/5.4
Software Architectural Design / Software Detailed Design -- this document satisfies the requirement for documented software architecture and per-unit design.
DO-178C Section 11.10
Software Design Description -- this document describes the architecture, data flow, and control flow of the software.
ISO 26262 Part 6, Clause 7-8
Software architectural design specification and unit design -- component decomposition, interfaces, and data structures.
Default Assurance Level
E

1.5 Document Overview

Section 2 presents the software architecture with component diagrams. Section 3 provides detailed per-component design. Section 4 covers data design. Section 5 specifies all interface contracts. Section 6 documents design constraints. Section 7 provides traceability from requirements to components and code.

2. Software Architecture

2.1 Architecture Overview

The system is decomposed into 1 components connected by 0 defined interface boundaries. Each component owns a set of requirements and variables that define its behavior contract.

2.2 Component Diagram

The following diagram shows the component dependency graph derived from interface specifications:

graph LR
  empty[No interfaces defined]

Specification Hierarchy

graph TD
  n_specs_stakeholder["specs/stakeholder\nL0 #124; stakeholder\n7 reqs"]
  n_specs_system["specs/system\nL1 #124; system\n116 reqs"]

  n_specs_stakeholder --> n_specs_system

2.3 Component Summary

#ComponentRequirementsVariablesInterfaces
1 parser 123 242 0

2.4 Specification Hierarchy

LevelSpec PathTypePrefixRequirements
0 specs/stakeholder stakeholder STK-REQ 7
1 specs/system system SYS-REQ 116

3. Component Design

This section provides detailed design for each component, including its interfaces, data structures, requirements, and traceability.

3.1 parser

3.1.2 Data Structures

VariableTypeDirectionDescription
json_input_is_well_formed bool input True when the provided JSON byte slice is well formed for the lookup case under evaluation.
addressed_path_exists bool input True when the requested key path resolves to a value in the JSON input under evaluation.
key_path_is_provided bool input True when the caller supplies at least one key-path segment for the lookup case under evaluation.
json_input_is_empty bool input True when the provided lookup input is empty.
input_is_incomplete_during_lookup bool input True when the input is truncated or incomplete before Get can complete the addressed lookup.
returns_existing_path_lookup_result bool output True when Get returns the addressed value, value type, end offset, and no error for a well-formed existing path lookup.
returns_missing_path_result_for_well_formed_lookup bool output True when Get reports the defined not-found outcome for a well-formed lookup whose addressed path does not exist.
returns_parse_error_for_incomplete_lookup bool output True when Get reports a parse-related error for an incomplete or truncated lookup input.
returns_root_value_without_key_path bool output True when Get returns the closest complete root JSON value for a well-formed input when no key path is provided.
returns_missing_path_result_for_empty_input bool output True when Get reports the defined not-found outcome for an empty input with a provided key path.
path_segment_is_object_key bool input True when the current lookup path segment is interpreted as an object-member key rather than as an array index.
segment_is_evaluated_at_current_scope bool input True when the current lookup segment is being matched against the current JSON structural scope rather than against a sibling or deeper subtree.
path_segment_is_array_index bool input True when the current lookup path segment is interpreted as an array index.
array_index_segment_is_valid bool input True when the current array-index path segment has valid index syntax.
array_index_is_in_bounds bool input True when the addressed array index is within the bounds of the addressed array.
array_index_is_out_of_bounds bool input True when the addressed array index exceeds the bounds of the addressed array.
escaped_json_object_key_is_present bool input True when the addressed object member key is encoded with JSON escape sequences in the payload.
decoded_path_segment_matches_escaped_key bool input True when the decoded lookup path segment matches the logical value of an escaped JSON object key.
addressed_value_is_string bool input True when the addressed successful lookup value is a JSON string token.
addressed_value_is_number bool input True when the addressed value is a JSON number token.
addressed_value_is_boolean bool input True when the addressed value is a JSON boolean token.
returns_value_from_current_scope_object_key bool output True when Get resolves the requested object-member path segment only against the current structural scope and returns that value.
returns_value_from_in_bounds_array_index bool output True when Get resolves a valid in-bounds array-index path segment and returns the addressed element.
returns_invalid_array_index_not_found bool output True when Get reports the defined not-found outcome for a malformed array-index path segment.
returns_oob_array_index_not_found bool output True when Get reports the defined not-found outcome for a valid but out-of-bounds array index.
returns_value_from_decoded_escaped_key bool output True when Get resolves an escaped JSON object key by comparing the decoded path segment to the logical key value.
returns_unquoted_raw_string_contents bool output True when Get returns JSON string contents without surrounding quotes and without JSON unescaping.
malformed_input_outside_addressed_token bool input True when malformed JSON appears outside the addressed token path rather than inside the token that lookup is trying to return.
addressed_token_can_be_isolated bool input True when Get can still isolate a complete addressed token or determine lookup absence despite malformed input elsewhere in the document.
returns_best_effort_lookup_result bool output True when Get preserves the corresponding success or not-found lookup result despite malformed input outside the addressed token path.
addressed_token_shape_is_invalid bool input True when the addressed token cannot be classified as string, object, array, number, boolean, or null.
returns_value_type_error bool output True when Get returns a value-type classification error for an invalid addressed token shape.
raw_string_token_is_well_formed bool input True when the addressed raw JSON string token is well formed and can be decoded.
returns_getstring_decoded_value bool output True when GetString returns the addressed value as a decoded Go string.
raw_number_token_is_integer_parseable bool input True when the addressed JSON number token can be parsed as an int64 value.
returns_getint_value bool output True when GetInt returns the addressed value as an int64.
raw_number_token_is_float_parseable bool input True when the addressed JSON number token can be parsed as a float64 value.
returns_getfloat_value bool output True when GetFloat returns the addressed value as a float64.
raw_boolean_token_is_well_formed bool input True when the addressed JSON boolean token is a valid `true` or `false` literal.
returns_getboolean_value bool output True when GetBoolean returns the addressed value as a Go bool.
addressed_array_is_well_formed bool input True when ArrayEach is operating on a well-formed addressed JSON array.
addressed_array_is_empty bool input True when ArrayEach is operating on an addressed array that contains no elements.
array_callback_receives_elements_in_order bool output True when ArrayEach invokes the callback for each addressed array element in encounter order.
empty_array_produces_no_callbacks bool output True when ArrayEach emits no callbacks for a well-formed empty addressed array.
malformed_array_input_returns_error bool output True when ArrayEach returns an error for malformed or unusable array input.
addressed_object_is_well_formed bool input True when ObjectEach is operating on a well-formed addressed JSON object.
addressed_object_is_empty bool input True when ObjectEach is operating on an addressed object that contains no entries.
object_callback_receives_entries bool output True when ObjectEach invokes the callback with the correct key, value, and value-type tuple for each addressed object entry.
object_callback_error_is_returned bool output True when ObjectEach returns an error produced by the callback instead of swallowing it.
empty_object_produces_no_entries bool output True when ObjectEach emits no entry callbacks for a well-formed empty addressed object.
malformed_object_input_returns_error bool output True when ObjectEach returns an error for malformed or unusable addressed object input.
object_callback_returns_error bool input True when the callback supplied to ObjectEach returns an error during iteration.
multipath_requests_are_provided bool input True when EachKey is called with one or more requested key paths.
eachkey_callback_receives_found_values bool output True when EachKey invokes the callback with the value and type for each requested path that is found during the scan.
missing_multipath_request_does_not_emit_callback bool output True when EachKey does not emit a found-value callback for a requested path that is absent.
eachkey_malformed_input_returns_error bool output True when EachKey surfaces an error for malformed or unusable input during the scan.
eachkey_completes_requested_scan bool output True when EachKey completes the requested multi-path scan and stops once the requested results have been determined.
set_path_is_provided bool input True when Set is called with at least one mutation path segment.
set_target_exists bool input True when the full addressed Set path already exists in the input JSON.
set_creates_missing_path bool output True when Set creates the missing addressed path inside a valid target container.
set_returns_updated_document bool output True when Set returns the updated JSON document for the addressed mutation case.
set_returns_not_found_error bool output True when Set returns `KeyPathNotFoundError` because the requested mutation path is not usable for the provided input.
delete_path_is_provided bool input True when Delete is called with at least one path segment.
delete_returns_empty_document_without_path bool output True when Delete returns an empty byte slice because no path segment was provided.
delete_target_exists bool input True when the addressed Delete target exists and can be isolated in the input JSON.
delete_input_is_unusable_for_requested_path bool input True when Delete cannot safely resolve the requested path because the input is malformed, truncated, or otherwise unusable for that deletion request.
delete_returns_document_without_target bool output True when Delete returns the JSON document with the addressed value removed.
delete_preserves_input_when_target_missing bool output True when Delete leaves the input unchanged because the addressed target is missing in otherwise usable input.
delete_returns_original_input_on_unusable_input bool output True when Delete returns the original byte payload unchanged because the input is unusable for the requested deletion.
delete_completes_without_panic bool output True when Delete completes the requested call path without panicking.
returns_unsafe_string_view bool output True when GetUnsafeString returns the addressed raw value bytes mapped directly as a Go string without JSON unescaping.
raw_boolean_literal_is_valid bool input True when ParseBoolean receives a valid boolean literal token.
returns_parseboolean_value bool output True when ParseBoolean returns the corresponding Go bool value.
returns_parseboolean_error bool output True when ParseBoolean returns the documented malformed-value error for an invalid boolean token.
raw_float_token_is_well_formed bool input True when ParseFloat receives a well-formed floating-point number token.
returns_parsefloat_value bool output True when ParseFloat returns the corresponding float64 value.
returns_parsefloat_error bool output True when ParseFloat returns the documented malformed-value error for a malformed numeric token.
raw_string_literal_is_well_formed bool input True when ParseString receives a well-formed raw JSON string literal body.
returns_parsestring_value bool output True when ParseString returns the corresponding decoded Go string value.
returns_parsestring_error bool output True when ParseString returns the documented malformed-value error for a malformed encoded string literal.
raw_int_token_is_well_formed bool input True when ParseInt receives a syntactically well-formed integer token that does not overflow int64.
raw_int_token_overflows_int64 bool input True when ParseInt receives an integer token whose magnitude exceeds the supported int64 range.
returns_parseint_value bool output True when ParseInt returns the corresponding int64 value.
returns_parseint_overflow_error bool output True when ParseInt returns the documented overflow error for an integer token outside the supported int64 range.
returns_parseint_malformed_error bool output True when ParseInt returns the documented malformed-value error for a non-integer or otherwise malformed token.
input_is_truncated_at_value_boundary bool input True when the JSON input is truncated at a value boundary where the value token ends at EOF with no closing delimiter (e.g., '{"a":1' with no closing brace).
returns_error_for_truncated_value_boundary bool output True when Get returns a parse-related error or not-found result for input truncated at a value boundary, without panicking.
input_is_truncated_mid_structure bool input True when the JSON input is truncated in the middle of a structural element where an object or array is opened but never closed.
returns_error_for_truncated_mid_structure bool output True when Get returns a parse-related error for input truncated mid-structure, without panicking.
input_is_truncated_mid_key bool input True when the JSON input is truncated in the middle of a key string where the key is not terminated by a closing quote.
returns_error_for_truncated_mid_key bool output True when Get returns a parse-related error for input truncated mid-key, without panicking.
tokenEnd_returns_len_data bool input True when the internal helper tokenEnd returns len(data) as a sentinel value indicating no delimiter was found in the remaining input.
caller_bounds_checks_tokenEnd_sentinel bool output True when all callers of tokenEnd treat the len(data) sentinel as an end-of-input condition and do not use it as an unchecked array index.
stringEnd_returns_negative_one bool input True when the internal helper stringEnd returns -1 indicating no closing quote was found.
caller_handles_stringEnd_sentinel bool output True when all callers of stringEnd treat -1 as a malformed-string condition and do not proceed with normal value extraction.
blockEnd_returns_negative_one bool input True when the internal helper blockEnd returns -1 indicating no matching closing bracket or brace was found.
caller_handles_blockEnd_sentinel bool output True when all callers of blockEnd treat -1 as a malformed-structure condition and do not proceed with normal value extraction.
path_segment_is_negative_array_index bool input True when the current path segment is a negative array index such as "[-1]".
returns_not_found_for_negative_array_index bool output True when Get returns the defined not-found result for a negative array index because negative indexing is not supported.
delete_input_is_truncated_at_value_boundary bool input True when Delete is called on input truncated at a value boundary where tokenEnd would return len(data) as a sentinel.
delete_returns_original_input_on_truncated_value bool output True when Delete returns the original byte payload unchanged for input truncated at a value boundary.
delete_completes_without_panic_on_truncated_value bool output True when Delete completes without panicking on input truncated at a value boundary.
delete_discards_internalGet_error bool input True when Delete discards an error returned by internalGet (assigns to underscore) instead of using it to short-circuit.
delete_propagates_internalGet_error bool output True when Delete uses an error returned by internalGet to short-circuit to the safe fallback path.
delete_array_input_is_truncated bool input True when Delete is called with an array-element path on input where the array is truncated.
delete_returns_original_input_on_truncated_array bool output True when Delete returns the original byte payload unchanged for truncated array input.
delete_completes_without_panic_on_truncated_array bool output True when Delete completes without panicking on truncated array input.
set_input_is_truncated bool input True when Set is called on truncated JSON input where path resolution encounters incomplete structural elements.
set_returns_error_for_truncated_input bool output True when Set returns an error for truncated input rather than producing corrupt output or panicking.
array_callback_returns_error bool input True when the Get call for an array element within ArrayEach returns an error.
array_callback_error_is_propagated bool output True when ArrayEach propagates the element-level Get error to the caller.
array_is_truncated_mid_element bool input True when ArrayEach encounters an array element that is truncated or incomplete.
returns_error_for_truncated_array_element bool output True when ArrayEach returns a parse-related error for a truncated array element, without panicking.
object_is_truncated_mid_entry bool input True when ObjectEach encounters an object entry whose value is truncated or incomplete.
returns_error_for_truncated_object_entry bool output True when ObjectEach returns a parse-related error for a truncated object entry, without panicking.
array_has_malformed_delimiter bool input True when ArrayEach encounters a malformed delimiter between array elements where a comma is expected but absent or wrong.
returns_error_for_malformed_array_delimiter bool output True when ArrayEach returns MalformedArrayError for a malformed delimiter between array elements.
delete_input_is_truncated_mid_structure bool input True when Delete is called on input truncated mid-structure with unclosed nested objects or arrays.
delete_returns_original_input_on_truncated_structure bool output True when Delete returns the original byte payload unchanged for mid-structure truncated input.
delete_completes_without_panic_on_truncated_structure bool output True when Delete completes without panicking on mid-structure truncated input.
raw_boolean_literal_is_partial bool input True when ParseBoolean receives a partial boolean literal such as "tru" or "fals".
returns_error_for_partial_boolean_literal bool output True when ParseBoolean returns MalformedValueError for a partial boolean literal.
raw_int_token_is_at_int64_max_boundary bool input True when ParseInt receives an integer token at the exact int64 boundary values (max 9223372036854775807 or min -9223372036854775808).
returns_correct_value_at_int64_boundary bool output True when ParseInt returns the correct int64 value at the exact boundary without overflow error.
raw_int_token_is_at_int64_max_plus_one bool input True when ParseInt receives an integer token exactly one beyond the int64 range (9223372036854775808 or -9223372036854775809).
returns_overflow_at_int64_max_plus_one bool output True when ParseInt returns OverflowIntegerError for an integer token exactly one beyond the int64 range.
raw_string_has_truncated_escape_sequence bool input True when ParseString receives a string containing a truncated escape sequence such as a lone backslash or incomplete unicode escape like '\u00'.
returns_error_for_truncated_escape_sequence bool output True when ParseString returns MalformedValueError for a truncated escape sequence.
raw_string_has_missing_low_surrogate bool input True when ParseString encounters a UTF-16 high surrogate escape not followed by a valid low surrogate escape.
substitutes_replacement_for_missing_low_surrogate bool output True when ParseString substitutes U+FFFD for a lone high surrogate, matching encoding/json behavior.
raw_string_has_invalid_low_surrogate bool input True when ParseString encounters a UTF-16 high surrogate followed by a unicode escape whose value is below the low surrogate range.
substitutes_replacement_for_invalid_low_surrogate bool output True when ParseString substitutes U+FFFD for a high surrogate followed by an invalid low surrogate, matching encoding/json behavior.
raw_string_has_backslash_at_end bool input True when ParseString encounters a string ending with a lone backslash with no character after it.
returns_error_for_backslash_at_end bool output True when ParseString returns MalformedValueError for a string ending with a lone backslash.
parseint_input_is_empty bool input True when ParseInt receives an empty byte slice.
returns_parseint_malformed_for_empty bool output True when ParseInt returns MalformedValueError for an empty byte slice.
parsefloat_input_is_empty bool input True when ParseFloat receives an empty byte slice.
returns_parsefloat_malformed_for_empty bool output True when ParseFloat returns MalformedValueError for an empty byte slice.
parseboolean_input_is_empty bool input True when ParseBoolean receives an empty byte slice.
returns_parseboolean_malformed_for_empty bool output True when ParseBoolean returns MalformedValueError for an empty byte slice.
parsestring_input_is_empty bool input True when ParseString receives an empty byte slice.
returns_parsestring_identity_for_empty bool output True when ParseString returns an empty Go string without error for an empty byte slice.
set_path_points_beyond_eof bool input True when Set is called with a path that resolves to a location beyond the end of available data.
set_returns_error_for_path_beyond_eof bool output True when Set returns an error for a path that resolves beyond the end of available data.
set_target_is_nested_in_existing_structure bool input True when Set is called with a multi-level path where intermediate levels exist but the leaf does not.
set_performs_nested_mutation_correctly bool output True when Set correctly creates missing nested structure and inserts the value at the correct location.
set_called_without_path bool input True when Set is called without any key path segments.
set_returns_error_without_path bool output True when Set returns KeyPathNotFoundError because no path segment was provided.
getstring_input_is_malformed bool input True when GetString is called on malformed input where the underlying Get call returns an error.
returns_getstring_error_for_malformed bool output True when GetString propagates the error from Get for malformed input.
getstring_value_has_truncated_escape bool input True when GetString addresses a JSON string value containing a truncated escape sequence.
returns_getstring_error_for_truncated_escape bool output True when GetString returns an error from ParseString for a truncated escape sequence.
getstring_addressed_value_is_not_string bool input True when GetString addresses a value that is not a JSON string.
returns_getstring_type_mismatch_error bool output True when GetString returns a type-mismatch error for a non-string addressed value.
getstring_input_is_empty bool input True when GetString is called on empty input.
returns_getstring_error_for_empty_input bool output True when GetString returns not-found or error for empty input.
getint_input_is_malformed bool input True when GetInt is called on malformed input where the underlying Get call returns an error.
returns_getint_error_for_malformed bool output True when GetInt propagates the error from Get for malformed input.
getint_value_overflows_int64 bool input True when GetInt addresses a JSON number token whose magnitude exceeds the int64 range.
returns_getint_overflow_error bool output True when GetInt returns the documented overflow error for a value exceeding int64 range.
getint_addressed_value_is_not_number bool input True when GetInt addresses a value that is not a JSON number.
returns_getint_type_mismatch_error bool output True when GetInt returns a type-mismatch error for a non-number addressed value.
getint_input_is_empty bool input True when GetInt is called on empty input.
returns_getint_error_for_empty_input bool output True when GetInt returns not-found or error for empty input.
getboolean_addressed_value_is_partial_literal bool input True when GetBoolean addresses a value that is a partial boolean literal due to truncation.
returns_getboolean_error_for_partial bool output True when GetBoolean returns an error from type classification or ParseBoolean for a partial boolean literal.
getunsafestring_input_is_malformed bool input True when GetUnsafeString is called on malformed input where the underlying Get call returns an error.
returns_getunsafestring_error_for_malformed bool output True when GetUnsafeString propagates the error from Get for malformed input.
getunsafestring_input_is_empty bool input True when GetUnsafeString is called on empty input.
returns_getunsafestring_error_for_empty bool output True when GetUnsafeString returns not-found or error for empty input.
getunsafestring_input_is_truncated_at_value_boundary bool input True when GetUnsafeString is called on input truncated at a value boundary.
returns_getunsafestring_error_for_truncated_value bool output True when GetUnsafeString propagates the error from Get for input truncated at a value boundary.
arrayeach_input_is_truncated_at_value_boundary bool input True when ArrayEach is called on input truncated at a value boundary.
returns_error_for_arrayeach_truncated_value bool output True when ArrayEach returns an error for input truncated at a value boundary, without panicking.
objecteach_input_is_truncated_mid_structure bool input True when ObjectEach is called on input truncated mid-structure where the object or a nested structure is not closed.
returns_error_for_objecteach_truncated_structure bool output True when ObjectEach returns an error for truncated mid-structure input, without panicking.
eachkey_tokenEnd_sentinel_reached bool input True when EachKey encounters a tokenEnd sentinel value during multi-path scanning.
eachkey_handles_sentinel_safely bool output True when EachKey treats the tokenEnd sentinel as an end-of-input condition and returns safely.
get_called_twice_with_same_input bool input True when Get is called twice with identical JSON input and identical key paths.
get_returns_identical_results bool output True when Get returns identical value slices, value types, offsets, and error values on both calls.
get_called_on_valid_input bool input True when Get is called on a non-nil JSON byte slice.
get_does_not_mutate_input bool output True when Get does not mutate the input byte slice during the call.
get_input_is_nil bool input True when Get is called with a nil byte slice as input.
get_returns_safe_result_for_nil bool output True when Get returns a not-found or error result without panicking for nil input.
get_input_is_deeply_nested bool input True when Get is called on JSON with deeply nested structures (64+ levels).
get_handles_deep_nesting_safely bool output True when Get returns a correct result or error for deeply nested input without panicking.
getstring_called_twice_with_same_input bool input True when GetString is called twice with identical JSON input and identical key paths.
getstring_returns_identical_results bool output True when GetString returns identical decoded string values and error values on both calls.
getstring_input_is_nil bool input True when GetString is called with a nil byte slice as input.
getstring_returns_safe_result_for_nil bool output True when GetString returns an empty string and error without panicking for nil input.
getstring_input_has_escaped_unicode bool input True when GetString addresses a JSON string containing escaped Unicode sequences.
getstring_decodes_and_preserves_semantics bool output True when GetString decodes escaped Unicode to correct Go string runes preserving semantic equivalence.
getstring_input_has_unicode_edge_cases bool input True when GetString addresses a JSON string containing Unicode edge cases like BOM or ZWJ.
getstring_handles_unicode_edges_safely bool output True when GetString handles Unicode edge cases correctly or returns a well-defined error.
typed_getter_called_twice_with_same_input bool input True when GetInt, GetFloat, or GetBoolean is called twice with identical input.
typed_getter_returns_identical_results bool output True when typed getters return identical typed values and error values on both calls.
typed_getter_input_is_nil bool input True when GetInt, GetFloat, or GetBoolean is called with a nil byte slice.
typed_getter_returns_safe_result_for_nil bool output True when typed getters return zero value and error without panicking for nil input.
getint_input_has_large_number_edge_case bool input True when GetInt addresses a JSON number with edge-case formatting like leading zeros or max-length digit strings.
getint_handles_large_numbers_safely bool output True when GetInt returns correct int64 or well-defined error for large-number edge cases.
traversal_called_twice_with_same_input bool input True when ArrayEach, ObjectEach, or EachKey is called twice with identical input.
traversal_returns_identical_results bool output True when traversal callbacks are invoked in the same order with same values on both calls.
traversal_input_is_nil bool input True when ArrayEach, ObjectEach, or EachKey is called with a nil byte slice.
traversal_returns_safe_result_for_nil bool output True when traversal returns error without invoking callbacks and without panicking for nil input.
traversal_input_is_deeply_nested bool input True when ArrayEach or ObjectEach is called on JSON with deeply nested structures.
traversal_handles_deep_nesting_safely bool output True when traversal handles deeply nested input safely without panicking or stack overflowing.
set_applied_twice_with_same_args bool input True when Set is called twice on the same input with the same value and key path.
set_second_call_produces_same_result bool output True when the second Set call produces the same output as the first application.
mutation_input_is_nil bool input True when Set or Delete is called with a nil byte slice.
mutation_returns_safe_result_for_nil bool output True when Set returns error and Delete returns nil/empty without panicking for nil input.
mutation_input_has_unicode_keys bool input True when Set or Delete is called with key paths containing Unicode characters.
mutation_handles_unicode_keys_safely bool output True when Set or Delete correctly resolves Unicode key paths or returns well-defined error.
getunsafestring_called_twice_with_same_input bool input True when GetUnsafeString is called twice with identical input.
getunsafestring_returns_identical_results bool output True when GetUnsafeString returns identical raw string values on both calls.
getunsafestring_input_is_nil bool input True when GetUnsafeString is called with a nil byte slice.
getunsafestring_returns_safe_result_for_nil bool output True when GetUnsafeString returns empty string and error without panicking for nil input.
getunsafestring_input_has_unicode_edge_cases bool input True when GetUnsafeString addresses a value with Unicode edge cases.
getunsafestring_handles_unicode_edges_safely bool output True when GetUnsafeString returns raw bytes as Go string without corruption for Unicode edge cases.
parse_helper_called_twice_with_same_input bool input True when a Parse helper is called twice with identical byte input.
parse_helper_returns_identical_results bool output True when Parse helpers return identical typed values and error values on both calls.
parse_helper_input_is_nil bool input True when a Parse helper is called with a nil byte slice.
parse_helper_returns_safe_result_for_nil bool output True when Parse helpers return zero value and error (or empty string) without panicking for nil input.
parsestring_input_has_standard_escapes bool input True when ParseString input contains standard JSON escape sequences.
parsestring_roundtrip_preserves_semantics bool output True when ParseString decoded string preserves semantic equivalence with original JSON encoding.
parseint_input_has_edge_case_number bool input True when ParseInt receives an edge-case numeric token like negative zero or very long digit strings.
parseint_handles_edge_numbers_safely bool output True when ParseInt returns correct int64 or well-defined error for edge-case numbers.
array_index int input The array index N addressed by an array-index path component [N]. Unbounded above; the boundary of interest is N versus the current length of the addressed array.
addressed_array_length int input The current element count of the array addressed by an array-index path component during Set mutation.
set_targets_array_index_beyond_length bool input True when Set addresses an array-index path component [N] where N >= the current length of the addressed array (the beyond-length partition of array_index).
set_targets_array_index_within_length bool input True when Set addresses an array-index path component [N] where N < the current length of the addressed array (the in-bounds partition of array_index, complement of set_targets_array_index_beyond_length).
set_appends_value_at_array_end bool output True when Set appends the value at the end of the addressed array (the new element's index becomes len(array)) and returns the mutated document, rather than overwriting an existing element or panicking.
path_component_length int input The byte length of a single caller-supplied key path component string. The boundary of interest is the empty-component case (length 0).
path_component_is_empty_string bool input True when any caller-supplied key path component is the empty string (the empty partition of path_component_length, length == 0). An empty-string component is neither a valid object key nor the [ array-index marker.
path_component_is_nonempty_string bool input True when every caller-supplied key path component is non-empty (the nonempty partition of path_component_length, complement of path_component_is_empty_string).
returns_not_found_for_empty_key_component bool output True when the parser treats an empty-string key path component as an unresolvable path, returning KeyPathNotFoundError for the Get family and Delete (and EachKey omitting the callback) or a defined error/document for Set.
completes_without_panic_on_empty_key_component bool output True when the parser completes the call without panicking for an empty-string key path component, never reaching an unguarded keys[i][0] / p[level][0] dereference (the OSS-Fuzz 4649128545288192 / hazard-sweep class).
addressed_container_is_array_or_object bool input True when the value addressed by the GetArrayLen/GetObjectLen key path is a JSON array (GetArrayLen) or object (GetObjectLen) container rather than a scalar or missing path.
returns_container_element_count bool output True when GetArrayLen returns the number of elements in the addressed array (0 for an empty array) or GetObjectLen returns the number of key-value pairs in the addressed object (0 for an empty object), with no caller callback invoked.
wildcard_path_resolves_to_every_matched_element bool output True when EachKeyWildcard/ArrayEachWildcard/SetWildcard fan out over every element matched by [*] components in document order (EachKeyWildcard one callback per matched combination, SetWildcard applies to every expanded concrete path), returning MalformedArrayError for a non-array container and treating an empty matched array as a no-op.
compiled_jsonpath_resolves_to_same_result_as_equivalent_key_path bool output True when ParsePath converts a JSONPath-style string ($.dot, [N], [*], "quoted") into the path-component slice accepted by Get/Set/Delete/ArrayEach/EachKey and CompiledPath methods are observationally equivalent to invoking the matching top-level function with the parsed components, with errEmptyPath for empty input and errMalformedPath for non-conforming syntax.
config_lenient_modes_are_opt_in_and_default_remains_strict bool output True when Config accepts single-quoted strings only with AllowSingleQuotes, passes unknown escape bytes through literally only with AllowUnknownEscapes, and the zero/default Config plus package-level functions retain strict RFC 8259 behavior.
reader_parser_provides_incremental_stream_access bool output True when ReaderParser resolves paths and iterates root arrays from an io.Reader while retaining only the active sliding window or value and reporting empty or malformed streams without panicking or looping.
Data Properties
VariableProperties
returns_existing_path_lookup_result Last_wins, commutative, idempotent
returns_missing_path_result_for_well_formed_lookup Last_wins, commutative, idempotent
returns_parse_error_for_incomplete_lookup Last_wins, commutative, idempotent
returns_root_value_without_key_path Last_wins, commutative, idempotent
returns_missing_path_result_for_empty_input Last_wins, commutative, idempotent
returns_value_from_in_bounds_array_index Last_wins, commutative, idempotent
returns_invalid_array_index_not_found Last_wins, commutative, idempotent
returns_oob_array_index_not_found Last_wins, commutative, idempotent
returns_value_from_decoded_escaped_key Last_wins, commutative, idempotent
returns_unquoted_raw_string_contents Last_wins, commutative, idempotent
returns_best_effort_lookup_result Last_wins, commutative, idempotent
returns_value_type_error Last_wins, commutative, idempotent
set_appends_value_at_array_end Last_wins, commutative, idempotent
returns_not_found_for_empty_key_component Last_wins, commutative, idempotent
completes_without_panic_on_empty_key_component Last_wins, commutative, idempotent
returns_container_element_count Last_wins, commutative, idempotent
wildcard_path_resolves_to_every_matched_element Last_wins, commutative, idempotent
compiled_jsonpath_resolves_to_same_result_as_equivalent_key_path Last_wins, commutative, idempotent
config_lenient_modes_are_opt_in_and_default_remains_strict Last_wins, commutative, idempotent
reader_parser_provides_incremental_stream_access Last_wins, commutative, idempotent

3.1.3 Requirements Traceability

RequirementPriorityCategoryStatus
STK-REQ-001 shall functional approved
STK-REQ-002 shall functional approved
STK-REQ-003 shall functional approved
STK-REQ-004 shall functional approved
STK-REQ-005 shall functional approved
STK-REQ-006 shall functional approved
STK-REQ-007 shall functional approved
SYS-REQ-001 shall functional approved
SYS-REQ-002 shall functional approved
SYS-REQ-003 shall functional approved
SYS-REQ-004 shall functional approved
SYS-REQ-005 shall functional approved
SYS-REQ-006 shall functional approved
SYS-REQ-007 shall functional approved
SYS-REQ-008 shall functional approved
SYS-REQ-009 shall functional approved
SYS-REQ-010 shall functional approved
SYS-REQ-011 shall functional approved
SYS-REQ-012 shall functional approved
SYS-REQ-013 shall functional approved
SYS-REQ-014 shall functional approved
SYS-REQ-015 shall functional approved
SYS-REQ-016 shall functional approved
SYS-REQ-017 shall functional approved
SYS-REQ-018 shall functional approved
SYS-REQ-019 shall functional approved
SYS-REQ-020 shall functional approved
SYS-REQ-021 shall functional approved
SYS-REQ-022 shall functional approved
SYS-REQ-023 shall functional approved
SYS-REQ-024 shall functional approved
SYS-REQ-025 shall functional approved
SYS-REQ-026 shall functional approved
SYS-REQ-027 shall functional approved
SYS-REQ-028 shall functional approved
SYS-REQ-029 shall functional approved
SYS-REQ-030 shall functional approved
SYS-REQ-031 shall functional approved
SYS-REQ-032 shall functional approved
SYS-REQ-033 shall functional approved
SYS-REQ-034 shall functional approved
SYS-REQ-035 shall functional approved
SYS-REQ-036 shall functional approved
SYS-REQ-037 shall functional approved
SYS-REQ-038 shall functional approved
SYS-REQ-039 shall functional approved
SYS-REQ-040 shall functional approved
SYS-REQ-041 shall functional approved
SYS-REQ-042 shall functional approved
SYS-REQ-043 shall functional approved
SYS-REQ-044 shall functional approved
SYS-REQ-045 shall functional approved
SYS-REQ-046 shall functional approved
SYS-REQ-047 shall functional approved
SYS-REQ-048 shall functional approved
SYS-REQ-049 shall functional approved
SYS-REQ-050 shall functional approved
SYS-REQ-051 shall functional approved
SYS-REQ-052 shall functional approved
SYS-REQ-053 shall functional approved
SYS-REQ-054 shall functional approved
SYS-REQ-055 shall functional approved
SYS-REQ-056 shall functional approved
SYS-REQ-057 shall functional approved
SYS-REQ-058 shall functional approved
SYS-REQ-059 shall functional approved
SYS-REQ-060 shall functional approved
SYS-REQ-061 shall functional approved
SYS-REQ-062 shall functional approved
SYS-REQ-063 shall functional approved
SYS-REQ-064 shall functional approved
SYS-REQ-065 shall functional approved
SYS-REQ-066 shall functional approved
SYS-REQ-067 shall functional approved
SYS-REQ-068 shall functional approved
SYS-REQ-069 shall functional approved
SYS-REQ-070 shall functional approved
SYS-REQ-071 shall functional approved
SYS-REQ-072 shall functional approved
SYS-REQ-073 shall functional approved
SYS-REQ-074 shall functional approved
SYS-REQ-075 shall functional approved
SYS-REQ-076 shall functional approved
SYS-REQ-077 shall functional approved
SYS-REQ-078 shall functional approved
SYS-REQ-079 shall functional approved
SYS-REQ-080 shall functional approved
SYS-REQ-081 shall functional approved
SYS-REQ-082 shall functional approved
SYS-REQ-083 shall functional approved
SYS-REQ-084 shall functional approved
SYS-REQ-085 shall functional approved
SYS-REQ-086 shall functional approved
SYS-REQ-087 shall functional approved
SYS-REQ-088 shall functional approved
SYS-REQ-089 shall functional approved
SYS-REQ-090 shall functional approved
SYS-REQ-091 shall functional approved
SYS-REQ-092 shall functional approved
SYS-REQ-093 shall functional approved
SYS-REQ-094 shall functional approved
SYS-REQ-095 shall functional approved
SYS-REQ-096 shall functional approved
SYS-REQ-097 shall functional approved
SYS-REQ-098 shall functional approved
SYS-REQ-099 shall functional approved
SYS-REQ-100 shall functional approved
SYS-REQ-101 shall functional approved
SYS-REQ-102 shall functional approved
SYS-REQ-103 shall functional approved
SYS-REQ-104 shall functional approved
SYS-REQ-105 shall functional approved
SYS-REQ-106 shall functional approved
SYS-REQ-107 shall functional approved
SYS-REQ-108 shall functional approved
SYS-REQ-109 shall functional approved
SYS-REQ-110 shall functional approved
SYS-REQ-111 shall functional approved
SYS-REQ-112 shall functional approved
SYS-REQ-113 shall functional approved
SYS-REQ-114 shall functional approved
SYS-REQ-115 shall functional approved
SYS-REQ-116 shall functional approved

4. Data Design

4.1 Variable Definitions

The system defines 242 variables across 1 components.

ComponentVariableTypeDirectionDescription
parser json_input_is_well_formed bool input True when the provided JSON byte slice is well formed for the lookup case under evaluation.
parser addressed_path_exists bool input True when the requested key path resolves to a value in the JSON input under evaluation.
parser key_path_is_provided bool input True when the caller supplies at least one key-path segment for the lookup case under evaluation.
parser json_input_is_empty bool input True when the provided lookup input is empty.
parser input_is_incomplete_during_lookup bool input True when the input is truncated or incomplete before Get can complete the addressed lookup.
parser returns_existing_path_lookup_result bool output True when Get returns the addressed value, value type, end offset, and no error for a well-formed existing path lookup.
parser returns_missing_path_result_for_well_formed_lookup bool output True when Get reports the defined not-found outcome for a well-formed lookup whose addressed path does not exist.
parser returns_parse_error_for_incomplete_lookup bool output True when Get reports a parse-related error for an incomplete or truncated lookup input.
parser returns_root_value_without_key_path bool output True when Get returns the closest complete root JSON value for a well-formed input when no key path is provided.
parser returns_missing_path_result_for_empty_input bool output True when Get reports the defined not-found outcome for an empty input with a provided key path.
parser path_segment_is_object_key bool input True when the current lookup path segment is interpreted as an object-member key rather than as an array index.
parser segment_is_evaluated_at_current_scope bool input True when the current lookup segment is being matched against the current JSON structural scope rather than against a sibling or deeper subtree.
parser path_segment_is_array_index bool input True when the current lookup path segment is interpreted as an array index.
parser array_index_segment_is_valid bool input True when the current array-index path segment has valid index syntax.
parser array_index_is_in_bounds bool input True when the addressed array index is within the bounds of the addressed array.
parser array_index_is_out_of_bounds bool input True when the addressed array index exceeds the bounds of the addressed array.
parser escaped_json_object_key_is_present bool input True when the addressed object member key is encoded with JSON escape sequences in the payload.
parser decoded_path_segment_matches_escaped_key bool input True when the decoded lookup path segment matches the logical value of an escaped JSON object key.
parser addressed_value_is_string bool input True when the addressed successful lookup value is a JSON string token.
parser addressed_value_is_number bool input True when the addressed value is a JSON number token.
parser addressed_value_is_boolean bool input True when the addressed value is a JSON boolean token.
parser returns_value_from_current_scope_object_key bool output True when Get resolves the requested object-member path segment only against the current structural scope and returns that value.
parser returns_value_from_in_bounds_array_index bool output True when Get resolves a valid in-bounds array-index path segment and returns the addressed element.
parser returns_invalid_array_index_not_found bool output True when Get reports the defined not-found outcome for a malformed array-index path segment.
parser returns_oob_array_index_not_found bool output True when Get reports the defined not-found outcome for a valid but out-of-bounds array index.
parser returns_value_from_decoded_escaped_key bool output True when Get resolves an escaped JSON object key by comparing the decoded path segment to the logical key value.
parser returns_unquoted_raw_string_contents bool output True when Get returns JSON string contents without surrounding quotes and without JSON unescaping.
parser malformed_input_outside_addressed_token bool input True when malformed JSON appears outside the addressed token path rather than inside the token that lookup is trying to return.
parser addressed_token_can_be_isolated bool input True when Get can still isolate a complete addressed token or determine lookup absence despite malformed input elsewhere in the document.
parser returns_best_effort_lookup_result bool output True when Get preserves the corresponding success or not-found lookup result despite malformed input outside the addressed token path.
parser addressed_token_shape_is_invalid bool input True when the addressed token cannot be classified as string, object, array, number, boolean, or null.
parser returns_value_type_error bool output True when Get returns a value-type classification error for an invalid addressed token shape.
parser raw_string_token_is_well_formed bool input True when the addressed raw JSON string token is well formed and can be decoded.
parser returns_getstring_decoded_value bool output True when GetString returns the addressed value as a decoded Go string.
parser raw_number_token_is_integer_parseable bool input True when the addressed JSON number token can be parsed as an int64 value.
parser returns_getint_value bool output True when GetInt returns the addressed value as an int64.
parser raw_number_token_is_float_parseable bool input True when the addressed JSON number token can be parsed as a float64 value.
parser returns_getfloat_value bool output True when GetFloat returns the addressed value as a float64.
parser raw_boolean_token_is_well_formed bool input True when the addressed JSON boolean token is a valid `true` or `false` literal.
parser returns_getboolean_value bool output True when GetBoolean returns the addressed value as a Go bool.
parser addressed_array_is_well_formed bool input True when ArrayEach is operating on a well-formed addressed JSON array.
parser addressed_array_is_empty bool input True when ArrayEach is operating on an addressed array that contains no elements.
parser array_callback_receives_elements_in_order bool output True when ArrayEach invokes the callback for each addressed array element in encounter order.
parser empty_array_produces_no_callbacks bool output True when ArrayEach emits no callbacks for a well-formed empty addressed array.
parser malformed_array_input_returns_error bool output True when ArrayEach returns an error for malformed or unusable array input.
parser addressed_object_is_well_formed bool input True when ObjectEach is operating on a well-formed addressed JSON object.
parser addressed_object_is_empty bool input True when ObjectEach is operating on an addressed object that contains no entries.
parser object_callback_receives_entries bool output True when ObjectEach invokes the callback with the correct key, value, and value-type tuple for each addressed object entry.
parser object_callback_error_is_returned bool output True when ObjectEach returns an error produced by the callback instead of swallowing it.
parser empty_object_produces_no_entries bool output True when ObjectEach emits no entry callbacks for a well-formed empty addressed object.
parser malformed_object_input_returns_error bool output True when ObjectEach returns an error for malformed or unusable addressed object input.
parser object_callback_returns_error bool input True when the callback supplied to ObjectEach returns an error during iteration.
parser multipath_requests_are_provided bool input True when EachKey is called with one or more requested key paths.
parser eachkey_callback_receives_found_values bool output True when EachKey invokes the callback with the value and type for each requested path that is found during the scan.
parser missing_multipath_request_does_not_emit_callback bool output True when EachKey does not emit a found-value callback for a requested path that is absent.
parser eachkey_malformed_input_returns_error bool output True when EachKey surfaces an error for malformed or unusable input during the scan.
parser eachkey_completes_requested_scan bool output True when EachKey completes the requested multi-path scan and stops once the requested results have been determined.
parser set_path_is_provided bool input True when Set is called with at least one mutation path segment.
parser set_target_exists bool input True when the full addressed Set path already exists in the input JSON.
parser set_creates_missing_path bool output True when Set creates the missing addressed path inside a valid target container.
parser set_returns_updated_document bool output True when Set returns the updated JSON document for the addressed mutation case.
parser set_returns_not_found_error bool output True when Set returns `KeyPathNotFoundError` because the requested mutation path is not usable for the provided input.
parser delete_path_is_provided bool input True when Delete is called with at least one path segment.
parser delete_returns_empty_document_without_path bool output True when Delete returns an empty byte slice because no path segment was provided.
parser delete_target_exists bool input True when the addressed Delete target exists and can be isolated in the input JSON.
parser delete_input_is_unusable_for_requested_path bool input True when Delete cannot safely resolve the requested path because the input is malformed, truncated, or otherwise unusable for that deletion request.
parser delete_returns_document_without_target bool output True when Delete returns the JSON document with the addressed value removed.
parser delete_preserves_input_when_target_missing bool output True when Delete leaves the input unchanged because the addressed target is missing in otherwise usable input.
parser delete_returns_original_input_on_unusable_input bool output True when Delete returns the original byte payload unchanged because the input is unusable for the requested deletion.
parser delete_completes_without_panic bool output True when Delete completes the requested call path without panicking.
parser returns_unsafe_string_view bool output True when GetUnsafeString returns the addressed raw value bytes mapped directly as a Go string without JSON unescaping.
parser raw_boolean_literal_is_valid bool input True when ParseBoolean receives a valid boolean literal token.
parser returns_parseboolean_value bool output True when ParseBoolean returns the corresponding Go bool value.
parser returns_parseboolean_error bool output True when ParseBoolean returns the documented malformed-value error for an invalid boolean token.
parser raw_float_token_is_well_formed bool input True when ParseFloat receives a well-formed floating-point number token.
parser returns_parsefloat_value bool output True when ParseFloat returns the corresponding float64 value.
parser returns_parsefloat_error bool output True when ParseFloat returns the documented malformed-value error for a malformed numeric token.
parser raw_string_literal_is_well_formed bool input True when ParseString receives a well-formed raw JSON string literal body.
parser returns_parsestring_value bool output True when ParseString returns the corresponding decoded Go string value.
parser returns_parsestring_error bool output True when ParseString returns the documented malformed-value error for a malformed encoded string literal.
parser raw_int_token_is_well_formed bool input True when ParseInt receives a syntactically well-formed integer token that does not overflow int64.
parser raw_int_token_overflows_int64 bool input True when ParseInt receives an integer token whose magnitude exceeds the supported int64 range.
parser returns_parseint_value bool output True when ParseInt returns the corresponding int64 value.
parser returns_parseint_overflow_error bool output True when ParseInt returns the documented overflow error for an integer token outside the supported int64 range.
parser returns_parseint_malformed_error bool output True when ParseInt returns the documented malformed-value error for a non-integer or otherwise malformed token.
parser input_is_truncated_at_value_boundary bool input True when the JSON input is truncated at a value boundary where the value token ends at EOF with no closing delimiter (e.g., '{"a":1' with no closing brace).
parser returns_error_for_truncated_value_boundary bool output True when Get returns a parse-related error or not-found result for input truncated at a value boundary, without panicking.
parser input_is_truncated_mid_structure bool input True when the JSON input is truncated in the middle of a structural element where an object or array is opened but never closed.
parser returns_error_for_truncated_mid_structure bool output True when Get returns a parse-related error for input truncated mid-structure, without panicking.
parser input_is_truncated_mid_key bool input True when the JSON input is truncated in the middle of a key string where the key is not terminated by a closing quote.
parser returns_error_for_truncated_mid_key bool output True when Get returns a parse-related error for input truncated mid-key, without panicking.
parser tokenEnd_returns_len_data bool input True when the internal helper tokenEnd returns len(data) as a sentinel value indicating no delimiter was found in the remaining input.
parser caller_bounds_checks_tokenEnd_sentinel bool output True when all callers of tokenEnd treat the len(data) sentinel as an end-of-input condition and do not use it as an unchecked array index.
parser stringEnd_returns_negative_one bool input True when the internal helper stringEnd returns -1 indicating no closing quote was found.
parser caller_handles_stringEnd_sentinel bool output True when all callers of stringEnd treat -1 as a malformed-string condition and do not proceed with normal value extraction.
parser blockEnd_returns_negative_one bool input True when the internal helper blockEnd returns -1 indicating no matching closing bracket or brace was found.
parser caller_handles_blockEnd_sentinel bool output True when all callers of blockEnd treat -1 as a malformed-structure condition and do not proceed with normal value extraction.
parser path_segment_is_negative_array_index bool input True when the current path segment is a negative array index such as "[-1]".
parser returns_not_found_for_negative_array_index bool output True when Get returns the defined not-found result for a negative array index because negative indexing is not supported.
parser delete_input_is_truncated_at_value_boundary bool input True when Delete is called on input truncated at a value boundary where tokenEnd would return len(data) as a sentinel.
parser delete_returns_original_input_on_truncated_value bool output True when Delete returns the original byte payload unchanged for input truncated at a value boundary.
parser delete_completes_without_panic_on_truncated_value bool output True when Delete completes without panicking on input truncated at a value boundary.
parser delete_discards_internalGet_error bool input True when Delete discards an error returned by internalGet (assigns to underscore) instead of using it to short-circuit.
parser delete_propagates_internalGet_error bool output True when Delete uses an error returned by internalGet to short-circuit to the safe fallback path.
parser delete_array_input_is_truncated bool input True when Delete is called with an array-element path on input where the array is truncated.
parser delete_returns_original_input_on_truncated_array bool output True when Delete returns the original byte payload unchanged for truncated array input.
parser delete_completes_without_panic_on_truncated_array bool output True when Delete completes without panicking on truncated array input.
parser set_input_is_truncated bool input True when Set is called on truncated JSON input where path resolution encounters incomplete structural elements.
parser set_returns_error_for_truncated_input bool output True when Set returns an error for truncated input rather than producing corrupt output or panicking.
parser array_callback_returns_error bool input True when the Get call for an array element within ArrayEach returns an error.
parser array_callback_error_is_propagated bool output True when ArrayEach propagates the element-level Get error to the caller.
parser array_is_truncated_mid_element bool input True when ArrayEach encounters an array element that is truncated or incomplete.
parser returns_error_for_truncated_array_element bool output True when ArrayEach returns a parse-related error for a truncated array element, without panicking.
parser object_is_truncated_mid_entry bool input True when ObjectEach encounters an object entry whose value is truncated or incomplete.
parser returns_error_for_truncated_object_entry bool output True when ObjectEach returns a parse-related error for a truncated object entry, without panicking.
parser array_has_malformed_delimiter bool input True when ArrayEach encounters a malformed delimiter between array elements where a comma is expected but absent or wrong.
parser returns_error_for_malformed_array_delimiter bool output True when ArrayEach returns MalformedArrayError for a malformed delimiter between array elements.
parser delete_input_is_truncated_mid_structure bool input True when Delete is called on input truncated mid-structure with unclosed nested objects or arrays.
parser delete_returns_original_input_on_truncated_structure bool output True when Delete returns the original byte payload unchanged for mid-structure truncated input.
parser delete_completes_without_panic_on_truncated_structure bool output True when Delete completes without panicking on mid-structure truncated input.
parser raw_boolean_literal_is_partial bool input True when ParseBoolean receives a partial boolean literal such as "tru" or "fals".
parser returns_error_for_partial_boolean_literal bool output True when ParseBoolean returns MalformedValueError for a partial boolean literal.
parser raw_int_token_is_at_int64_max_boundary bool input True when ParseInt receives an integer token at the exact int64 boundary values (max 9223372036854775807 or min -9223372036854775808).
parser returns_correct_value_at_int64_boundary bool output True when ParseInt returns the correct int64 value at the exact boundary without overflow error.
parser raw_int_token_is_at_int64_max_plus_one bool input True when ParseInt receives an integer token exactly one beyond the int64 range (9223372036854775808 or -9223372036854775809).
parser returns_overflow_at_int64_max_plus_one bool output True when ParseInt returns OverflowIntegerError for an integer token exactly one beyond the int64 range.
parser raw_string_has_truncated_escape_sequence bool input True when ParseString receives a string containing a truncated escape sequence such as a lone backslash or incomplete unicode escape like '\u00'.
parser returns_error_for_truncated_escape_sequence bool output True when ParseString returns MalformedValueError for a truncated escape sequence.
parser raw_string_has_missing_low_surrogate bool input True when ParseString encounters a UTF-16 high surrogate escape not followed by a valid low surrogate escape.
parser substitutes_replacement_for_missing_low_surrogate bool output True when ParseString substitutes U+FFFD for a lone high surrogate, matching encoding/json behavior.
parser raw_string_has_invalid_low_surrogate bool input True when ParseString encounters a UTF-16 high surrogate followed by a unicode escape whose value is below the low surrogate range.
parser substitutes_replacement_for_invalid_low_surrogate bool output True when ParseString substitutes U+FFFD for a high surrogate followed by an invalid low surrogate, matching encoding/json behavior.
parser raw_string_has_backslash_at_end bool input True when ParseString encounters a string ending with a lone backslash with no character after it.
parser returns_error_for_backslash_at_end bool output True when ParseString returns MalformedValueError for a string ending with a lone backslash.
parser parseint_input_is_empty bool input True when ParseInt receives an empty byte slice.
parser returns_parseint_malformed_for_empty bool output True when ParseInt returns MalformedValueError for an empty byte slice.
parser parsefloat_input_is_empty bool input True when ParseFloat receives an empty byte slice.
parser returns_parsefloat_malformed_for_empty bool output True when ParseFloat returns MalformedValueError for an empty byte slice.
parser parseboolean_input_is_empty bool input True when ParseBoolean receives an empty byte slice.
parser returns_parseboolean_malformed_for_empty bool output True when ParseBoolean returns MalformedValueError for an empty byte slice.
parser parsestring_input_is_empty bool input True when ParseString receives an empty byte slice.
parser returns_parsestring_identity_for_empty bool output True when ParseString returns an empty Go string without error for an empty byte slice.
parser set_path_points_beyond_eof bool input True when Set is called with a path that resolves to a location beyond the end of available data.
parser set_returns_error_for_path_beyond_eof bool output True when Set returns an error for a path that resolves beyond the end of available data.
parser set_target_is_nested_in_existing_structure bool input True when Set is called with a multi-level path where intermediate levels exist but the leaf does not.
parser set_performs_nested_mutation_correctly bool output True when Set correctly creates missing nested structure and inserts the value at the correct location.
parser set_called_without_path bool input True when Set is called without any key path segments.
parser set_returns_error_without_path bool output True when Set returns KeyPathNotFoundError because no path segment was provided.
parser getstring_input_is_malformed bool input True when GetString is called on malformed input where the underlying Get call returns an error.
parser returns_getstring_error_for_malformed bool output True when GetString propagates the error from Get for malformed input.
parser getstring_value_has_truncated_escape bool input True when GetString addresses a JSON string value containing a truncated escape sequence.
parser returns_getstring_error_for_truncated_escape bool output True when GetString returns an error from ParseString for a truncated escape sequence.
parser getstring_addressed_value_is_not_string bool input True when GetString addresses a value that is not a JSON string.
parser returns_getstring_type_mismatch_error bool output True when GetString returns a type-mismatch error for a non-string addressed value.
parser getstring_input_is_empty bool input True when GetString is called on empty input.
parser returns_getstring_error_for_empty_input bool output True when GetString returns not-found or error for empty input.
parser getint_input_is_malformed bool input True when GetInt is called on malformed input where the underlying Get call returns an error.
parser returns_getint_error_for_malformed bool output True when GetInt propagates the error from Get for malformed input.
parser getint_value_overflows_int64 bool input True when GetInt addresses a JSON number token whose magnitude exceeds the int64 range.
parser returns_getint_overflow_error bool output True when GetInt returns the documented overflow error for a value exceeding int64 range.
parser getint_addressed_value_is_not_number bool input True when GetInt addresses a value that is not a JSON number.
parser returns_getint_type_mismatch_error bool output True when GetInt returns a type-mismatch error for a non-number addressed value.
parser getint_input_is_empty bool input True when GetInt is called on empty input.
parser returns_getint_error_for_empty_input bool output True when GetInt returns not-found or error for empty input.
parser getboolean_addressed_value_is_partial_literal bool input True when GetBoolean addresses a value that is a partial boolean literal due to truncation.
parser returns_getboolean_error_for_partial bool output True when GetBoolean returns an error from type classification or ParseBoolean for a partial boolean literal.
parser getunsafestring_input_is_malformed bool input True when GetUnsafeString is called on malformed input where the underlying Get call returns an error.
parser returns_getunsafestring_error_for_malformed bool output True when GetUnsafeString propagates the error from Get for malformed input.
parser getunsafestring_input_is_empty bool input True when GetUnsafeString is called on empty input.
parser returns_getunsafestring_error_for_empty bool output True when GetUnsafeString returns not-found or error for empty input.
parser getunsafestring_input_is_truncated_at_value_boundary bool input True when GetUnsafeString is called on input truncated at a value boundary.
parser returns_getunsafestring_error_for_truncated_value bool output True when GetUnsafeString propagates the error from Get for input truncated at a value boundary.
parser arrayeach_input_is_truncated_at_value_boundary bool input True when ArrayEach is called on input truncated at a value boundary.
parser returns_error_for_arrayeach_truncated_value bool output True when ArrayEach returns an error for input truncated at a value boundary, without panicking.
parser objecteach_input_is_truncated_mid_structure bool input True when ObjectEach is called on input truncated mid-structure where the object or a nested structure is not closed.
parser returns_error_for_objecteach_truncated_structure bool output True when ObjectEach returns an error for truncated mid-structure input, without panicking.
parser eachkey_tokenEnd_sentinel_reached bool input True when EachKey encounters a tokenEnd sentinel value during multi-path scanning.
parser eachkey_handles_sentinel_safely bool output True when EachKey treats the tokenEnd sentinel as an end-of-input condition and returns safely.
parser get_called_twice_with_same_input bool input True when Get is called twice with identical JSON input and identical key paths.
parser get_returns_identical_results bool output True when Get returns identical value slices, value types, offsets, and error values on both calls.
parser get_called_on_valid_input bool input True when Get is called on a non-nil JSON byte slice.
parser get_does_not_mutate_input bool output True when Get does not mutate the input byte slice during the call.
parser get_input_is_nil bool input True when Get is called with a nil byte slice as input.
parser get_returns_safe_result_for_nil bool output True when Get returns a not-found or error result without panicking for nil input.
parser get_input_is_deeply_nested bool input True when Get is called on JSON with deeply nested structures (64+ levels).
parser get_handles_deep_nesting_safely bool output True when Get returns a correct result or error for deeply nested input without panicking.
parser getstring_called_twice_with_same_input bool input True when GetString is called twice with identical JSON input and identical key paths.
parser getstring_returns_identical_results bool output True when GetString returns identical decoded string values and error values on both calls.
parser getstring_input_is_nil bool input True when GetString is called with a nil byte slice as input.
parser getstring_returns_safe_result_for_nil bool output True when GetString returns an empty string and error without panicking for nil input.
parser getstring_input_has_escaped_unicode bool input True when GetString addresses a JSON string containing escaped Unicode sequences.
parser getstring_decodes_and_preserves_semantics bool output True when GetString decodes escaped Unicode to correct Go string runes preserving semantic equivalence.
parser getstring_input_has_unicode_edge_cases bool input True when GetString addresses a JSON string containing Unicode edge cases like BOM or ZWJ.
parser getstring_handles_unicode_edges_safely bool output True when GetString handles Unicode edge cases correctly or returns a well-defined error.
parser typed_getter_called_twice_with_same_input bool input True when GetInt, GetFloat, or GetBoolean is called twice with identical input.
parser typed_getter_returns_identical_results bool output True when typed getters return identical typed values and error values on both calls.
parser typed_getter_input_is_nil bool input True when GetInt, GetFloat, or GetBoolean is called with a nil byte slice.
parser typed_getter_returns_safe_result_for_nil bool output True when typed getters return zero value and error without panicking for nil input.
parser getint_input_has_large_number_edge_case bool input True when GetInt addresses a JSON number with edge-case formatting like leading zeros or max-length digit strings.
parser getint_handles_large_numbers_safely bool output True when GetInt returns correct int64 or well-defined error for large-number edge cases.
parser traversal_called_twice_with_same_input bool input True when ArrayEach, ObjectEach, or EachKey is called twice with identical input.
parser traversal_returns_identical_results bool output True when traversal callbacks are invoked in the same order with same values on both calls.
parser traversal_input_is_nil bool input True when ArrayEach, ObjectEach, or EachKey is called with a nil byte slice.
parser traversal_returns_safe_result_for_nil bool output True when traversal returns error without invoking callbacks and without panicking for nil input.
parser traversal_input_is_deeply_nested bool input True when ArrayEach or ObjectEach is called on JSON with deeply nested structures.
parser traversal_handles_deep_nesting_safely bool output True when traversal handles deeply nested input safely without panicking or stack overflowing.
parser set_applied_twice_with_same_args bool input True when Set is called twice on the same input with the same value and key path.
parser set_second_call_produces_same_result bool output True when the second Set call produces the same output as the first application.
parser mutation_input_is_nil bool input True when Set or Delete is called with a nil byte slice.
parser mutation_returns_safe_result_for_nil bool output True when Set returns error and Delete returns nil/empty without panicking for nil input.
parser mutation_input_has_unicode_keys bool input True when Set or Delete is called with key paths containing Unicode characters.
parser mutation_handles_unicode_keys_safely bool output True when Set or Delete correctly resolves Unicode key paths or returns well-defined error.
parser getunsafestring_called_twice_with_same_input bool input True when GetUnsafeString is called twice with identical input.
parser getunsafestring_returns_identical_results bool output True when GetUnsafeString returns identical raw string values on both calls.
parser getunsafestring_input_is_nil bool input True when GetUnsafeString is called with a nil byte slice.
parser getunsafestring_returns_safe_result_for_nil bool output True when GetUnsafeString returns empty string and error without panicking for nil input.
parser getunsafestring_input_has_unicode_edge_cases bool input True when GetUnsafeString addresses a value with Unicode edge cases.
parser getunsafestring_handles_unicode_edges_safely bool output True when GetUnsafeString returns raw bytes as Go string without corruption for Unicode edge cases.
parser parse_helper_called_twice_with_same_input bool input True when a Parse helper is called twice with identical byte input.
parser parse_helper_returns_identical_results bool output True when Parse helpers return identical typed values and error values on both calls.
parser parse_helper_input_is_nil bool input True when a Parse helper is called with a nil byte slice.
parser parse_helper_returns_safe_result_for_nil bool output True when Parse helpers return zero value and error (or empty string) without panicking for nil input.
parser parsestring_input_has_standard_escapes bool input True when ParseString input contains standard JSON escape sequences.
parser parsestring_roundtrip_preserves_semantics bool output True when ParseString decoded string preserves semantic equivalence with original JSON encoding.
parser parseint_input_has_edge_case_number bool input True when ParseInt receives an edge-case numeric token like negative zero or very long digit strings.
parser parseint_handles_edge_numbers_safely bool output True when ParseInt returns correct int64 or well-defined error for edge-case numbers.
parser array_index int input The array index N addressed by an array-index path component [N]. Unbounded above; the boundary of interest is N versus the current length of the addressed array.
parser addressed_array_length int input The current element count of the array addressed by an array-index path component during Set mutation.
parser set_targets_array_index_beyond_length bool input True when Set addresses an array-index path component [N] where N >= the current length of the addressed array (the beyond-length partition of array_index).
parser set_targets_array_index_within_length bool input True when Set addresses an array-index path component [N] where N < the current length of the addressed array (the in-bounds partition of array_index, complement of set_targets_array_index_beyond_length).
parser set_appends_value_at_array_end bool output True when Set appends the value at the end of the addressed array (the new element's index becomes len(array)) and returns the mutated document, rather than overwriting an existing element or panicking.
parser path_component_length int input The byte length of a single caller-supplied key path component string. The boundary of interest is the empty-component case (length 0).
parser path_component_is_empty_string bool input True when any caller-supplied key path component is the empty string (the empty partition of path_component_length, length == 0). An empty-string component is neither a valid object key nor the [ array-index marker.
parser path_component_is_nonempty_string bool input True when every caller-supplied key path component is non-empty (the nonempty partition of path_component_length, complement of path_component_is_empty_string).
parser returns_not_found_for_empty_key_component bool output True when the parser treats an empty-string key path component as an unresolvable path, returning KeyPathNotFoundError for the Get family and Delete (and EachKey omitting the callback) or a defined error/document for Set.
parser completes_without_panic_on_empty_key_component bool output True when the parser completes the call without panicking for an empty-string key path component, never reaching an unguarded keys[i][0] / p[level][0] dereference (the OSS-Fuzz 4649128545288192 / hazard-sweep class).
parser addressed_container_is_array_or_object bool input True when the value addressed by the GetArrayLen/GetObjectLen key path is a JSON array (GetArrayLen) or object (GetObjectLen) container rather than a scalar or missing path.
parser returns_container_element_count bool output True when GetArrayLen returns the number of elements in the addressed array (0 for an empty array) or GetObjectLen returns the number of key-value pairs in the addressed object (0 for an empty object), with no caller callback invoked.
parser wildcard_path_resolves_to_every_matched_element bool output True when EachKeyWildcard/ArrayEachWildcard/SetWildcard fan out over every element matched by [*] components in document order (EachKeyWildcard one callback per matched combination, SetWildcard applies to every expanded concrete path), returning MalformedArrayError for a non-array container and treating an empty matched array as a no-op.
parser compiled_jsonpath_resolves_to_same_result_as_equivalent_key_path bool output True when ParsePath converts a JSONPath-style string ($.dot, [N], [*], "quoted") into the path-component slice accepted by Get/Set/Delete/ArrayEach/EachKey and CompiledPath methods are observationally equivalent to invoking the matching top-level function with the parsed components, with errEmptyPath for empty input and errMalformedPath for non-conforming syntax.
parser config_lenient_modes_are_opt_in_and_default_remains_strict bool output True when Config accepts single-quoted strings only with AllowSingleQuotes, passes unknown escape bytes through literally only with AllowUnknownEscapes, and the zero/default Config plus package-level functions retain strict RFC 8259 behavior.
parser reader_parser_provides_incremental_stream_access bool output True when ReaderParser resolves paths and iterates root arrays from an io.Reader while retaining only the active sliding window or value and reporting empty or malformed streams without panicking or looping.

4.2 Data Properties

Variables with special merge, deduplication, or comparison properties:

ComponentVariableProperties
parser returns_existing_path_lookup_result Last_wins, commutative, idempotent
parser returns_missing_path_result_for_well_formed_lookup Last_wins, commutative, idempotent
parser returns_parse_error_for_incomplete_lookup Last_wins, commutative, idempotent
parser returns_root_value_without_key_path Last_wins, commutative, idempotent
parser returns_missing_path_result_for_empty_input Last_wins, commutative, idempotent
parser returns_value_from_in_bounds_array_index Last_wins, commutative, idempotent
parser returns_invalid_array_index_not_found Last_wins, commutative, idempotent
parser returns_oob_array_index_not_found Last_wins, commutative, idempotent
parser returns_value_from_decoded_escaped_key Last_wins, commutative, idempotent
parser returns_unquoted_raw_string_contents Last_wins, commutative, idempotent
parser returns_best_effort_lookup_result Last_wins, commutative, idempotent
parser returns_value_type_error Last_wins, commutative, idempotent
parser set_appends_value_at_array_end Last_wins, commutative, idempotent
parser returns_not_found_for_empty_key_component Last_wins, commutative, idempotent
parser completes_without_panic_on_empty_key_component Last_wins, commutative, idempotent
parser returns_container_element_count Last_wins, commutative, idempotent
parser wildcard_path_resolves_to_every_matched_element Last_wins, commutative, idempotent
parser compiled_jsonpath_resolves_to_same_result_as_equivalent_key_path Last_wins, commutative, idempotent
parser config_lenient_modes_are_opt_in_and_default_remains_strict Last_wins, commutative, idempotent
parser reader_parser_provides_incremental_stream_access Last_wins, commutative, idempotent

4.3 Data Flow

Data flows between components via the interface boundaries defined in Section 5. Input variables are consumed from upstream callers; output variables are produced for downstream callees. The direction field in the variable definitions indicates whether a variable is an input (consumed), output (produced), or mode (operating state).

5. Interface Design

5.1 Interface Specification Table

The system defines 0 interface boundaries.

#CallerCalleeTypeSignatureDescriptionAssumptionsGuarantees

5.2 Protocol Details

5.3 Error Handling Contracts

Each interface boundary follows a contract-based error handling pattern:

6. Design Constraints

Constraint CategoryDescription
Assurance LevelDefault assurance level: E. Components may override with higher levels as needed.
LanguageCore implementation in Go. Web UI in SvelteKit/TypeScript. Formal verification via external Kind2/JKind solvers.
PlatformCross-platform (Linux, macOS, Windows). External solver dependencies are optional.
SecurityInput validation on all external boundaries (HTTP, JSON-RPC, subprocess). HTML output uses auto-escaping to prevent XSS.
PerformanceDocument generation must complete in under 10 seconds for projects with up to 1000 requirements.

7. Traceability

7.1 Requirement-to-Component Mapping

Each requirement is assigned to exactly one component. The following table shows the distribution of requirements across components.

ComponentRequirement IDsTotal ReqsRequirement TypesCategories
parser STK-REQ-001 STK-REQ-002 STK-REQ-003 STK-REQ-004 STK-REQ-005 STK-REQ-006 STK-REQ-007 SYS-REQ-001 SYS-REQ-002 SYS-REQ-003 SYS-REQ-004 SYS-REQ-005 SYS-REQ-006 SYS-REQ-007 SYS-REQ-008 SYS-REQ-009 SYS-REQ-010 SYS-REQ-011 SYS-REQ-012 SYS-REQ-013 SYS-REQ-014 SYS-REQ-015 SYS-REQ-016 SYS-REQ-017 SYS-REQ-018 SYS-REQ-019 SYS-REQ-020 SYS-REQ-021 SYS-REQ-022 SYS-REQ-023 SYS-REQ-024 SYS-REQ-025 SYS-REQ-026 SYS-REQ-027 SYS-REQ-028 SYS-REQ-029 SYS-REQ-030 SYS-REQ-031 SYS-REQ-032 SYS-REQ-033 SYS-REQ-034 SYS-REQ-035 SYS-REQ-036 SYS-REQ-037 SYS-REQ-038 SYS-REQ-039 SYS-REQ-040 SYS-REQ-041 SYS-REQ-042 SYS-REQ-043 SYS-REQ-044 SYS-REQ-045 SYS-REQ-046 SYS-REQ-047 SYS-REQ-048 SYS-REQ-049 SYS-REQ-050 SYS-REQ-051 SYS-REQ-052 SYS-REQ-053 SYS-REQ-054 SYS-REQ-055 SYS-REQ-056 SYS-REQ-057 SYS-REQ-058 SYS-REQ-059 SYS-REQ-060 SYS-REQ-061 SYS-REQ-062 SYS-REQ-063 SYS-REQ-064 SYS-REQ-065 SYS-REQ-066 SYS-REQ-067 SYS-REQ-068 SYS-REQ-069 SYS-REQ-070 SYS-REQ-071 SYS-REQ-072 SYS-REQ-073 SYS-REQ-074 SYS-REQ-075 SYS-REQ-076 SYS-REQ-077 SYS-REQ-078 SYS-REQ-079 SYS-REQ-080 SYS-REQ-081 SYS-REQ-082 SYS-REQ-083 SYS-REQ-084 SYS-REQ-085 SYS-REQ-086 SYS-REQ-087 SYS-REQ-088 SYS-REQ-089 SYS-REQ-090 SYS-REQ-091 SYS-REQ-092 SYS-REQ-093 SYS-REQ-094 SYS-REQ-095 SYS-REQ-096 SYS-REQ-097 SYS-REQ-098 SYS-REQ-099 SYS-REQ-100 SYS-REQ-101 SYS-REQ-102 SYS-REQ-103 SYS-REQ-104 SYS-REQ-105 SYS-REQ-106 SYS-REQ-107 SYS-REQ-108 SYS-REQ-109 SYS-REQ-110 SYS-REQ-111 SYS-REQ-112 SYS-REQ-113 SYS-REQ-114 SYS-REQ-115 SYS-REQ-116 123 123 guarantee, 0 assumption, 0 constraint, 0 derived Functional Requirements (123)

7.2 Component-to-Code Mapping

Code files implementing each component, derived from implemented_by trace links.

ComponentImplementation Files
parser No code links