intersystems · isc-dchui · Oct 20, 2025 · Oct 30, 2025
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,51 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `latest/cls/pkg/isc/json/`: Core IRIS ObjectScript sources (adaptor, mapping, utils).
+- `latest/internal/testing/unit_tests/UnitTest/isc/json/`: Unit tests using `%UnitTest.TestCase`.
+- `latest/docs/` and `latest/README.md`: User docs and notes.
+- `latest/module.xml`: ZPM module manifest for packaging/testing.
+
+## Source Control
+- Perforce is used instead of git.
+- If a file is not checked out in perforce, run p4 edit or p4 add as needed before making edits
+
+## Build, Test, and Development Commands
+- Compile sources (from IRIS terminal in the correct namespace):
+  - `zpm "install isc.json"`
+- Run tests via ZPM (prompt for instance and namespace):
+  - Prefer this interactive shell snippet so you can choose the IRIS instance and namespace at run time:
+    ```sh
+    read -r -p "IRIS instance name: " IRISINST
+    read -r -p "Namespace to run tests: " NS
+    iris session "$IRISINST" -U "$NS" <<'EOF'
+_system
+SYS
+zpm "isc.json test"
+halt
+EOF
+    ```
+  - To run a single test case, replace the `zpm` line with, for example:
+    ```sh
+    zpm "isc.json test -only -DUnitTest.Case=UnitTest.isc.json.exportArray"
+    ```
+  - If already inside an IRIS terminal in your target namespace, you can simply run:
+    - `zpm "isc.json test"`
+
+## Coding Style & Naming Conventions
+- One class per `.cls` file; keep class path aligned with package.
+- Methods (including tests): PascalCase; avoid underscores.
+- Indentation: 4 spaces or tabs consistently; align `Try/Catch`/`While` blocks.
+- Use `///` for concise class/method docs; prefer code examples over prose.
+- Methods should throw errors instead of returning %Status unless overriding a method that requires returning %Status.
+
+## Testing Guidelines
+- Place tests under `latest/internal/testing/unit_tests/UnitTest/isc/json` in `UnitTest.isc.json.*` packages.
+- Name test methods `Test...` and keep assertions focused and readable.
+- Keep tests hermetic: no external I/O or network; use `%DynamicObject`/`%DynamicArray` fixtures.
+- Run tests locally before pushing; ensure new tests pass and do not break existing ones.
+
+## Security & Configuration Tips
+- Do not include real data/PII in fixtures.
+- Prefer configuration via parameters over hardcoding environment paths.
+- Validate JSON with `%DynamicAbstractObject` APIs; avoid unsafe string parsing.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,81 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.0] - 2025-09-18
+
+### Added 
+- HSIEO-13278: Add %JSONImportArray, %JSONExportToDynamicObject and %JSONExportArray.
+
+### Changed
+- HSIEO-13278: Refactor %JSONExport* methods to export to %DynamicObject and have other %JSONExport* methods call out to it. Update datatypes with JSONTYPE of runtime since that is now updated to not need extra escaping for LogicalToJSON().
+
+### Fixed
+- HSIEO-13278: Fix bug where invalid mapping would use base mapping. Throw error instead
+- HSIEO-13655: Fix ILLEGAL VALUE in export generation due to invalid third arg to %Set() - caused by HSIEO-13278.
+
+## [3.4.1] - 2025-09-03
+
+### Fixed
+- HSIEO-13346: Fix %JSONNewDefault handling to avoid METHOD DOES NOT EXIST errors
+
+## [3.4.0] - 2025-08-22
+
+### Added 
+- HSIEO-13279: Add new code generated method %JSONNewDefault. This will do default handling for %JSONNew 
+which is to return %New() of the corresponding class if not persistent. 
+If persistent, try to match against ID or unique indices based on what is available 
+(ID will override unique index if both are present).
+Update user guide and readme.
+
+## [3.3.0] - 2025-08-06
+
+### Added 
+- HSIEO-12322: New JSONTYPE of runtime to dynamically determine JSON type
+- HSIEO-10522: Add IDField and IncludeID in jsonMappingInfo
+
+### Changed
+- HSIEO-13080: Add Author info to module from "Ownership of AppModules" confluence page
+
+## [3.2.1] - 2024-07-01
+
+### Fixed
+- APPS-23837: Array property keys are not properly escaped by generated %JSONExport() code
+- APPS-23826: Fix bug in camelCase conversion when second char is a number.
+- HSIEO-10881: Fix bug in json generator dynamic object import.
+
+## [3.2.0] - 2024-04-10
+
+### Added 
+- APPS-21020: New method %JSONMappingInfo which returns the parsed mapping info for a given JSON mapping given the mapping name. 
+Useful for creating utilities that rely on the JSON mapping metadata
+
+## [3.1.0] - 2023-10-18
+
+### Changed
+- HSIEO-5398: Ensure `IncludeID` default matches `%JSONINCLUDEID` default of 1.
+
+## [3.0.0] - 2023-09-27
+
+### Changed
+- HSIEO-8297: IPM Adoption
+- HSIEO-9269, HSIEO-9402: Deprecate % in perforce path
+
+## [2.2.2] - 2023-09-15 
+
+## [2.2.1] - 2023-06-03
+
+## [2.2.0] - 2023-08-16
+
+### Fixed 
+- APPS-20986: Ensure `<property name>IsValid()` errors are returned if import fails 
+rather than generic JSON import error which obscures away error details.
+
+## [2.1.0] - 2023-03-08
+
+### Added 
+- APPS-12974: Add support for %DynamicObject/Array properties, then remove usage of %Extends against
+the class being compiled.
+
 ## [2.0.1] - 2024-12-04
 
 ### Fixed
@@ -27,7 +102,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - APPS-13390: All `%pkg.isc.json.dataType.*` classes 
 - APPS-13390: Overridden error macros for working on Cache (now only supported on IRIS so not needed)
 
-
 ## [1.0.0] - 2022-04-21
 - Last released version before CHANGELOG existed.
-
diff --git a/README.md b/README.md
@@ -6,13 +6,13 @@ Note: a minimum platform version of InterSystems IRIS 2018.1 is required.
 
 ### Installation: ZPM
 
-If you already have the [ObjectScript Package Manager](https://openexchange.intersystems.com/package/ObjectScript-Package-Manager-2), installation is as easy as:
+If you already have the [InterSystems Package Manager](https://github.com/intersystems/ipm), installation is as easy as:
 ```
 zpm "install isc.json"
 ```
 
 ## User Guide
-See [isc.json User Guide](https://github.com/intersystems/isc-json/blob/master/docs/user-guide.md).
+See [isc.json User Guide](./docs/user-guide.md).
 
 ## Support
 If you find a bug or would like to request an enhancement, [report an issue](https://github.com/intersystems/isc-json/issues/new). If you have a question, feel free to post it on the [InterSystems Developer Community](https://community.intersystems.com/).
@@ -29,4 +29,4 @@ We use [SemVer](http://semver.org/) for versioning. Declare your dependencies us
 See also the list of [contributors](https://github.com/intersystems/isc-json/graphs/contributors) who participated in this project.
 
 ## License
-This project is licensed under the MIT License - see the [LICENSE](https://github.com/intersystems/isc-json/blob/master/LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/intersystems/isc-json/blob/master/LICENSE) file for details.