diff --git a/docs/modules/baselibs/json/docs/architecture/index.rst b/docs/modules/baselibs/json/docs/architecture/index.rst index c0efce84bf..7fbd7614f9 100644 --- a/docs/modules/baselibs/json/docs/architecture/index.rst +++ b/docs/modules/baselibs/json/docs/architecture/index.rst @@ -133,3 +133,10 @@ Lower Level Components :safety: ASIL_B :status: valid :fulfils: comp_req__json__deserialization, comp_req__json__asil + +.. comp_arc_sta:: vajson + :id: comp_arc_sta__baselibs__vajson + :security: YES + :safety: ASIL_B + :status: valid + :fulfils: comp_req__json__deserialization, comp_req__json__serialization, comp_req__json__user_format, comp_req__json__lang_idioms, comp_req__json__lang_infra, comp_req__json__type_compatibility, comp_req__json__asil, comp_req__vajson__validation, comp_req__vajson__deserialization_rfc_ext, comp_req__vajson__event_callbacks, comp_req__vajson__unicode, comp_req__vajson__binary_content diff --git a/docs/modules/baselibs/json/docs/index.rst b/docs/modules/baselibs/json/docs/index.rst index a23588d2fc..7e1d66608f 100644 --- a/docs/modules/baselibs/json/docs/index.rst +++ b/docs/modules/baselibs/json/docs/index.rst @@ -31,6 +31,7 @@ JSON-Library architecture/index.rst json_wrapper/index.rst nlohman_json/index.rst + vajson/index.rst safety_analysis/fmea.rst safety_analysis/dfa.rst diff --git a/docs/modules/baselibs/json/docs/json_wrapper/requirements/index.rst b/docs/modules/baselibs/json/docs/json_wrapper/requirements/index.rst index 7833ce180e..91250b2230 100644 --- a/docs/modules/baselibs/json/docs/json_wrapper/requirements/index.rst +++ b/docs/modules/baselibs/json/docs/json_wrapper/requirements/index.rst @@ -23,9 +23,9 @@ Requirements :realizes: wp__requirements_comp Due to low complexity, the requirements of the JSON component were not split into the "sub" components -"JSON Wrapper" and "nlohman_json". Reasoning is the low number of requirements (only about ten). +"JSON Wrapper", "nlohman_json" and "vajson". Reasoning is the low number of requirements (only about ten). The component split was done nevertheless, because "JSON Wrapper" is implemented as part of the S-CORE project and -"nlohman_json" is reused from open source. +"nlohman_json" and "vajson" is reused from open source. So the requirements for "JSON Wrapper" are documented in :need:`doc__json_requirements` (all requirements which are "fulfilled_by" :need:`comp_arc_sta__baselibs__json_wrapper`) diff --git a/docs/modules/baselibs/json/docs/vajson/index.rst b/docs/modules/baselibs/json/docs/vajson/index.rst new file mode 100644 index 0000000000..d8ccfff54b --- /dev/null +++ b/docs/modules/baselibs/json/docs/vajson/index.rst @@ -0,0 +1,172 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +VaJson +##################### + +.. note:: Document header + +.. document:: vajson + :id: doc__vajson + :status: valid + :safety: ASIL_B + :security: NO + :realizes: wp__cmpt_request + :tags: component_request + + +Abstract +======== + +We propose adding support for JSON parsing via the automotive established parser VaJson within S-CORE. + +This component request describes a json parser to be used within applications of the Eclipse S-CORE project. + +This requests adds VaJson, a SAX-based JSON parser for Eclipse S-CORE applications that enables parsing of JSON data for configuration and data exchange. + + +Motivation +========== + +VaJson provides a safety-qualified JSON parser designed for automotive environments. It has passed ASIL D compliance within Vector, offering safety artifacts that significantly reduce the effort required to adapt to S-CORE qualification processes. Its API follows automotive standards, ensuring easier integration, consistent practices, and lower risk compared to non-qualified alternatives. + +The VaJson source code successfully passed Vector’s internal ASIL D compliance process, demonstrating adherence to the highest automotive safety standards. Artifacts produced during this process—such as the safety manual, safety analysis, cybersecurity analysis, and detailed design—combined with ASIL-D qualified code, provide a strong foundation for simplifying adaptation to S-CORE’s internal qualification requirements. + + + +Rationale +========= + +VaJson was chosen because it is already ASIL D qualified (within Vector processes) and comes with complete safety and cybersecurity artifacts. This reduces the effort to meet S-CORE internal processes. + +The parser uses a SAX-based design, which is efficient for embedded systems and avoids high memory usage. + +Its API is familiar in automotive projects, making integration easier and reducing risk compared to introducing a new or generic parser. + + +Specification +============= + +VVajson fully meets all generic requirements outlined in https://github.com/eclipse-score/score/blob/main/docs/modules/baselibs/json/docs/requirements/index.rst. + +In addition, Vajson satisfies the extended requirements specified in https://github.com/eclipse-score/score/pull/2358/files (docs/modules/baselibs/json/docs/vajson/requirements/index.rst). +The extended requirements are also listed here below. + +- JSON Validation + VaJson shall provide a service to check the well-formedness of JSON data. Errors must include the reason and location in the document for malformed JSON and invalid schemata. + +- JSON Deserialization RFC extensions + VaJson shall parse JSON data according to RFC8259 from files and character buffers. The parser shall ignore trailing commas and accept hexadecimal integers. + +- JSON Event Callbacks + VaJson shall support event-driven parsing, notifying the user for each simple type and providing start/end events for complex types. + +- Unicode Support + VaJson shall decode and encode UTF-8 strings. + +- Binary Content Support + VaJson shall allow plain binary content and binary strings represented as JSON values. + + +Backwards Compatibility +======================= + +VaJson will be integrated as an optional backend through the existing S-CORE JSON wrapper. Users can configure which JSON backend to use (e.g., VaJson or nlohmann), ensuring no breaking changes to existing functionality. + + +Security Impact +=============== + +Potential security concerns and mitigations for VaJson: + +- Malformed JSON Attacks + Threat: Supplying intentionally malformed or deeply nested JSON to cause excessive CPU or memory consumption. + Mitigation: Handled by design within VaJson. VaJson uses a SAX-based streaming parser, which detects malformed JSON during parsing and prevents full processing of invalid input. + +- Schema Abuse + Threat: Using oversized keys/values or unexpected schema elements to bypass validation or trigger buffer overflows. + Mitigation: Handled by design within VaJson. Input size and structure are validated during parsing. + + + +Safety Impact +============= + +A full safety analysis for VaJson exists in an external format and addresses all identified concerns with appropriate measures. Example: + +FM-VaJson-NumberConversion +Details: Number conversion from textual JSON representation to a numerical value could change the value. +Effect: Incorrect numerical values may violate safety requirements. +Measure: Use only well-known standard library functions for number conversion, verified through unit testing. + +All concerns listed in the external safety analysis have been implemented and verified in the source code and tests. + +**Expected ASIL Level:** + +ASIL B. + +**Classification:** + +Safety-relevant component. + + +**Safety Related Functionality Required From Other Components** + +- This component requires common types/API functionality that is safe. + This includes base functionality like error handling, STL-functionality (eg. safe version of std::vector, std::span...) and aborts. + +- This component requires general OS related functionality that is safe. + This includes functionality for converting integers between host and network and acquiring endianness of the system (For FEAT_REQ__vajson__binary_content). + +- This component requires conversions of primitive types to strings that is safe. + Note: It's under investigation if this can be provided in the feature request. + +License Impact +============== + +[How could the copyright impacted by the license of the new contribution?] + + +How to Teach This +================= + +- Update baselibs/README.md + Clearly display configuration options for JSON parsing. The new component introduces multiple backend solutions, and users need visibility into available configurations. + + +- Use the inc_json incubation repo + Add user documentation inside inc_json/README.md to explain usage, integration steps, and best practices for the new JSON parsing backend. + + +Rejected Ideas +============== + +None. + + +Open Issues +=========== + +- S-CORE process compliance and Vectors role + The task of adapting the new component to be S-CORE process compliant is currently unassigned, and Vector will not create the required S-CORE process documentation (e.g., safety and security analysis). + + +Footnotes +========= + + +.. toctree:: + + requirements/index.rst + diff --git a/docs/modules/baselibs/json/docs/vajson/requirements/index.rst b/docs/modules/baselibs/json/docs/vajson/requirements/index.rst new file mode 100644 index 0000000000..3605371773 --- /dev/null +++ b/docs/modules/baselibs/json/docs/vajson/requirements/index.rst @@ -0,0 +1,74 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Requirements +============ + +In addition to the common JSON requirements shared by the different backends (such as "vajson" and ""nlohmann_json"), "vajson" offers extended capabilities. +These additional features are captured as requirements in the following section. + +.. comp_req:: JSON Validation + :id: comp_req__vajson__validation + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + + vaJson shall provide a service to check the well-formedness of JSON data. + Errors shall be reported including the error reason and the location in the JSON document for malformed JSON and invalid schemata (user-defined errors). + +.. comp_req:: JSON Deserialization RFC extensions + :id: comp_req__vajson__deserialization_rfc_ext + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + + vaJson shall provide a service to ignore trailing commas and accept hexadecimal integers. + +.. comp_req:: JSON Event Callbacks + :id: comp_req__vajson__event_callbacks + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + + vaJson shall provide a service to listen to events for every parsed JSON item. + The user shall be notified for every simple type directly, and for every complex type using start and end events. + +.. comp_req:: Unicode Support + :id: comp_req__vajson__unicode + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + + vaJson shall provide support for UTF-8 encoded strings. + UTF-8 encoded strings shall be decoded and encoded by vaJson. + +.. comp_req:: Binary Content Support + :id: comp_req__vajson__binary_content + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: feat_req__baselibs__json_library + :status: valid + + vaJson shall allow for plain binary content and binary strings. + Both types are represented as JSON values and handled accordingly (i.e., they must follow the JSON specification for values). +