1# @ohos.util.json (JSON Parsing and Generation)
2
3The JSON module provides a series of APIs for converting JSON text into JSON objects or values and converting objects into JSON strings.
4
5>**NOTE**
6>
7>The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9
10## Modules to Import
11
12```ts
13import { JSON } from '@kit.ArkTS';
14```
15
16## Transformer
17
18type Transformer = (this: Object, key: string, value: Object) => Object | undefined | null
19
20Defines the type of the conversion result function.
21
22**Atomic service API**: This API can be used in atomic services since API version 12.
23
24**System capability**: SystemCapability.Utils.Lang
25
26**Parameters**
27
28| Name| Type  | Mandatory| Description           |
29| ------ | ------ | ---- | --------------- |
30| this   | Object | Yes| Object to which the key-value pair to parse belongs.|
31| key  | string | Yes| Key to parse.|
32| value  | Object | Yes| Value of the key.|
33
34**Returns**
35
36| Type| Description|
37| -------- | -------- |
38| Object \| undefined \| null | Object obtained after parsing, undefined, or null.|
39
40## BigIntMode
41
42Enumerates the modes for processing BigInt.
43
44**Atomic service API**: This API can be used in atomic services since API version 12.
45
46**System capability**: SystemCapability.Utils.Lang
47
48| Name| Value| Description           |
49| ------ | ------ | --------------- |
50| DEFAULT   | 0 |BigInt is not supported.|
51| PARSE_AS_BIGINT   | 1 |Parses an integer that is less than -(2^53-1) or greater than (2^53-1) as BigInt.|
52| ALWAYS_PARSE_AS_BIGINT   | 2 |Parses all integers as BigInt.|
53
54## ParseOptions
55
56Describes the parsing options, which can define the mode for processing BigInt.
57
58**Atomic service API**: This API can be used in atomic services since API version 12.
59
60**System capability**: SystemCapability.Utils.Lang
61
62| Name| Type| Mandatory|Description           |
63| ------ | ------ | ---- | --------------- |
64| bigIntMode   | [BigIntMode](#bigintmode) | Yes|Mode for processing BigInt.|
65
66## JSON.parse
67
68parse(text: string, reviver?: Transformer, options?: ParseOptions): Object | null
69
70Parses a JSON string into an ArkTS object or null.
71
72**Atomic service API**: This API can be used in atomic services since API version 12.
73
74**System capability**: SystemCapability.Utils.Lang
75
76**Parameters**
77
78| Name| Type  | Mandatory| Description           |
79| ------ | ------ | ---- | --------------- |
80| text   | string | Yes| Valid JSON string.|
81| reviver  | [Transformer](#transformer) | No| Conversion function. This parameter can be used to modify the value generated after parsing. The default value is undefined.|
82| options   | [ParseOptions](#parseoptions) | No| Parsing options. This parameter is used to control the type of the parsing result. The default value is undefined.|
83
84**Returns**
85
86| Type| Description|
87| -------- | -------- |
88| Object \| null | ArkTS object or null (if null is passed in).|
89
90**Error codes**
91
92For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
93
94| ID| Error Message|
95| -------- | -------- |
96| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
97
98**Example**
99
100```ts
101let jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
102let obj = JSON.parse(jsonText);
103
104let options: JSON.ParseOptions = {
105  bigIntMode: JSON.BigIntMode.PARSE_AS_BIGINT,
106}
107let numberText = '{"largeNumber":112233445566778899}';
108let numberObj = JSON.parse(numberText,(key: string, value: Object | undefined | null): Object | undefined | null => {
109  if(key === "largeNumber") return value;
110  return value;
111},options) as Object;
112
113console.info((numberObj as object)?.["largeNumber"]);
114// Expected output: 112233445566778899
115```
116
117
118## JSON.stringify
119
120stringify(value: Object, replacer?: (number | string)[] | null, space?: string | number): string
121
122Converts an ArkTS object or array into a JSON string. In the case of a container, linear containers are supported, but non-linear containers are not.
123
124**Atomic service API**: This API can be used in atomic services since API version 12.
125
126**System capability**: SystemCapability.Utils.Lang
127
128**Parameters**
129
130| Name| Type| Mandatory| Description|
131| -------- | -------- | -------- | -------- |
132| value | Object | Yes| ArkTS object or array. In the case of a container, linear containers are supported, but non-linear containers are not.|
133| replacer | number[] \| string[] \| null | No| If an array is passed in, only the keys in the array are serialized to the final JSON string. If null is passed in, all keys of the object are serialized. The default value is undefined.|
134| space | string \| number | No| Indentation, white space, or line break characters inserted into the output JSON string for readability purposes. If a number is passed in, it indicates the number of space characters to be used as indentation. If a string is passed in, the string is inserted before the output JSON string. If null is passed in, no white space is used. The default value is an empty string.|
135
136**Returns**
137
138| Type| Description|
139| -------- | -------- |
140| string | JSON string after conversion.|
141
142**Error codes**
143
144For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
145
146| ID| Error Message|
147| -------- | -------- |
148| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
149
150**Example**
151
152```ts
153interface Person {
154  name: string;
155  age: number;
156  city: string;
157}
158let obj = {"name": "John", "age": 30, "city": "ChongQing"} as Person;
159let str1 = JSON.stringify(obj, ["name"]);
160```
161
162
163## JSON.stringify
164
165stringify(value: Object, replacer?: Transformer, space?: string | number): string
166
167Converts an ArkTS object or array into a JSON string. In the case of a container, linear containers are supported, but non-linear containers are not.
168
169**Atomic service API**: This API can be used in atomic services since API version 12.
170
171**System capability**: SystemCapability.Utils.Lang
172
173**Parameters**
174
175| Name| Type| Mandatory| Description|
176| -------- | -------- | -------- | -------- |
177| value | Object | Yes| ArkTS object or array. In the case of a container, linear containers are supported, but non-linear containers are not.|
178| replacer | [Transformer](#transformer) | No| During serialization, each key of the serialized value is converted and processed by this function. The default value is undefined.|
179| space | string \| number | No| Indentation, white space, or line break characters inserted into the output JSON string for readability purposes. If a number is passed in, it indicates the number of space characters to be used as indentation. If a string is passed in, the string is inserted before the output JSON string. If null is passed in, no white space is used. The default value is an empty string.|
180
181**Returns**
182
183| Type| Description|
184| -------- | -------- |
185| string | JSON string after conversion.|
186
187**Error codes**
188
189For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
190
191| ID| Error Message|
192| -------- | -------- |
193| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
194
195**Example**
196
197```ts
198function replacer(key: string, value: Object): Object {
199  if (typeof value === "string") {
200    return value.toUpperCase();
201  }
202  return value;
203}
204interface Person {
205  name: string;
206  age: number;
207  city: string;
208}
209
210let obj = {"name": "John", "age": 30, "city": "ChongQing"} as Person;
211let str2 = JSON.stringify(obj, replacer);
212```
213
214
215## JSON.has
216
217has(obj: object, property: string): boolean
218
219Checks whether an ArkTS object contains a key. This API can be used for related operations after [JSON.parse](#jsonparse) is called to parse a JSON string. This API supports only valid JSON strings whose outermost layer is in dictionary format (in braces instead of square brackets).
220
221**Atomic service API**: This API can be used in atomic services since API version 12.
222
223**System capability**: SystemCapability.Utils.Lang
224
225**Parameters**
226
227| Name| Type| Mandatory| Description|
228| -------- | -------- | -------- | -------- |
229| obj | object | Yes| ArkTS object.|
230| property | string | Yes| Key to check.|
231
232**Returns**
233
234| Type| Description|
235| -------- | -------- |
236| boolean | **true**: The ArkTS object contains the key.<br>**false**: The ArkTS object does not contain the key.|
237
238**Error codes**
239
240For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
241
242| ID| Error Message|
243| -------- | -------- |
244| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
245
246**Example**
247
248```ts
249const jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
250let obj = JSON.parse(jsonText);
251let rst = JSON.has(obj, "name");
252```
253
254
255## JSON.remove
256
257remove(obj: object, property: string): void
258
259Removes a key from an ArkTS object. This API can be used for related operations after [JSON.parse](#jsonparse) is called to parse a JSON string. This API supports only valid JSON strings whose outermost layer is in dictionary format (in braces instead of square brackets).
260
261**Atomic service API**: This API can be used in atomic services since API version 12.
262
263**System capability**: SystemCapability.Utils.Lang
264
265**Parameters**
266
267| Name| Type| Mandatory| Description|
268| -------- | -------- | -------- | -------- |
269| obj | object | Yes| ArkTS object.|
270| property | string | Yes| Key to remove.|
271
272**Error codes**
273
274For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
275
276| ID| Error Message|
277| -------- | -------- |
278| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
279
280**Example**
281
282```ts
283const jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
284let obj = JSON.parse(jsonText);
285let rst = JSON.remove(obj, "name");
286```
287