Summary<\/b>: June Blender provides a primer about JSON.\nHonorary Scripting Guy, June Blender, here. Today I’m going to introduce you to JSON.<\/p>\n
June is a writer for the Azure Active Directory SDK. She is also a frequent contributor to the Hey, Scripting Guy! Blog and for PowerShell.org. She lives in magnificent Escalante, Utah, where she works remotely when she’s not out hiking, kayaking, or convincing lost tourists to try Windows PowerShell. She believes that outstanding documentation is a collaborative effort, and she welcomes your comments and contributions. Follow her on Twitter at @juneb_get_help<\/a>. To read more by June, see these Hey, Scripting Guy! Blog posts<\/a>. \nI’ve been having a lot of fun learning web programming and working in Microsoft Azure and Azure PowerShell. I’ve noticed that I’m encountering a lot more JSON and a lot less XML over time. So, I thought I’d give our beginners a little primer on JSON.\nJavaScript Object Notation (JSON) is a “lightweight data-interchange format.” It is a way for programs to talk to each other, which is easy for humans to read and write, and easy for machines to parse and generate. It’s also really compressible. Unlike XML, which is wordy, you can squish JSON into a very few bytes so it’s small enough to include in fields with character limits, like the headers in the HTTP requests that web programs use to communicate.\nA JSON document is a string that looks like a hash table with name=value (or name:value) pairs, such as {“Color”=”Purple”} and {“State”:”Utah”}. It allows nesting, such as the “address” element this Wikipedia<\/a> example:<\/p>\n {<\/p>\n “firstName”: “John”,<\/p>\n “lastName”: “Smith”,<\/p>\n “isAlive”: true,<\/p>\n “age”: 25,<\/p>\n “height_cm”: 167.64,<\/p>\n “address”: {<\/p>\n “streetAddress”: “21 2nd Street”,<\/p>\n “city”: “New York”,<\/p>\n “state”: “NY”,<\/p>\n “postalCode”: “10021-3100”<\/p>\n }<\/p>\n }\nJSON documents that are used for interprogram communication are based on a schema. The schemas are also written in JSON and are easy to interpret. You can use a JSON schema to determine how to write a JSON document, and then after writing, use it to validate a JSON document.\nFortunately, JSON is very easy to manage in Windows PowerShell. The ConvertFrom-Json<\/b> cmdlet converts the JSON object into a custom object (PSCustomObject). JSON is case-sensitive, but the custom objects are case-insensitive.\nTo get a JSON string from a JSON file, use the Get-Content<\/b> cmdlet with its Raw<\/b> parameter. <\/p>\n PS C:> Get-Content -Raw -Path .myJson.json<\/p>\n {<\/p>\n “firstName”: “John”,<\/p>\n “lastName”: “Smith”,<\/p>\n “isAlive”: true,<\/p>\n “age”: 25,<\/p>\n “height_cm”: 167.64,<\/p>\n “address”: {<\/p>\n “streetAddress”: “21 2nd Street”,<\/p>\n “city”: “New York”,<\/p>\n “state”: “NY”,<\/p>\n “postalCode”: “10021-3100”<\/p>\n }<\/p>\n }\nTo convert it to a custom object, pipe the JSON string to the ConvertFrom-Json<\/b> cmdlet:<\/p>\n PS C:> $j = Get-Content -Raw -Path .myJson.json | ConvertFrom-Json<\/p>\n PS C:> $j<\/p>\n firstName : John<\/p>\n lastName : Smith<\/p>\n isAlive : True<\/p>\n age : 25<\/p>\n height_cm : 167.64<\/p>\n address : @{streetAddress=21 2nd Street; city=New York; state=NY; postalCode=10021-3100}<\/p>\n PS C:> $j.address<\/p>\n streetAddress city state postalCode<\/p>\n ————- —- —– ———-<\/p>\n 21 2nd Street New York NY 10021-3100\nThe Raw<\/b> parameter tells Get-Content<\/b> to ignore line breaks and return a single string. You can tell how many strings you have by counting the number of objects that are returned. Without Raw<\/b>, you get 13 separate strings. With Raw<\/b>, you get a single string.<\/p>\n PS C:> (Get-Content -Path .myJson.json).count<\/p>\n 13<\/p>\n PS C:> (Get-Content -Path .myJson.json -Raw).count<\/p>\n 1\nIf you forget the Raw<\/b> parameter and pipe multiple strings to ConvertFrom-Json<\/b>, you get this distinctive error message, which is Pig Latin for “Did you forget the Raw<\/b> parameter?”<\/p>\n ConvertFrom-Json : Invalid object passed in, ‘:’ or ‘}’ expected. (1): {<\/p>\n At line:1 char:20<\/p>\n + cat .myJson.json | ConvertFrom-Json<\/p>\n + ~~~~~~~~~~~~~~~~<\/p>\n + CategoryInfo : NotSpecified: (:) [ConvertFrom-Json], ArgumentException<\/p>\n + FullyQualifiedErrorId : System.ArgumentException,Microsoft.PowerShell.Commands.ConvertFromJsonCommand\nThe ConvertFrom-Json<\/b> cmdlet converts each JSON string into a custom object. It converts each name-value pair into a note property<\/b> and its value.<\/p>\n PS C:> $j = Get-Content -Raw -Path .myJson.json | ConvertFrom-Json<\/p>\n PS C:> $j | Get-Member<\/p>\n TypeName: System.Management.Automation.PSCustomObject<\/p>\n Name MemberType Definition<\/p>\n —- ———- ———-<\/p>\n Equals Method bool Equals(System.Object obj)<\/p>\n GetHashCode Method int GetHashCode()<\/p>\n GetType Method type GetType()<\/p>\n ToString Method string ToString()<\/p>\n address NoteProperty System.Management.Automation.PSCustomObject<\/p>\n age NoteProperty System.Int32 age=25<\/p>\n firstName NoteProperty System.String firstName=John<\/p>\n height_cm NoteProperty System.Decimal height_cm=167.64<\/p>\n isAlive NoteProperty System.Boolean isAlive=True<\/p>\n lastName NoteProperty System.String lastName=Smith<\/p>\n For example, it converts this:<\/p>\n “firstName”: “John”\n…into a firstName<\/b> note property with a value of John<\/b>:<\/p>\n PS C:> $j.firstName<\/p>\n John\nWhen it encounters a nested JSON object, like the one in the value of address<\/b>, it converts the value into a nested custom object with note properties representing each name-value pair.\nFor example, it converts this:<\/p>\n “address”: {<\/p>\n “streetAddress”: “21 2nd Street”,<\/p>\n “city”: “New York”,<\/p>\n “state”: “NY”,<\/p>\n “postalCode”: “10021-3100”<\/p>\n }\nTo:<\/p>\n PS C:> $j.address<\/p>\n streetAddress city state postalCode<\/p>\n ————- —- —– ———-<\/p>\n 21 2nd Street New York NY 10021-3100\n…which is a custom object with its own note properties:<\/p>\n PS C:> $j.address | Get-Member<\/p>\n TypeName: System.Management.Automation.PSCustomObject<\/p>\n Name MemberType Definition<\/p>\n —- ———- ———-<\/p>\n Equals Method bool Equals(System.Object obj)<\/p>\n GetHashCode Method int GetHashCode()<\/p>\n GetType Method type GetType()<\/p>\n ToString Method string ToString()<\/p>\n city NoteProperty System.String city=New York<\/p>\n postalCode NoteProperty System.String postalCode=10021-3100<\/p>\n state NoteProperty System.String state=NY<\/p>\n streetAddress NoteProperty System.String streetAddress=21 2nd Street<\/p>\n You can edit the custom object and then use the ConvertTo-Json<\/b> cmdlet and Set-Content<\/b> cmdlets to replace the value in the .json file. Let’s move John Smith to a more scenic location:<\/p>\n $j.address.city = “Escalante”<\/p>\n $j.address.state = “UT”<\/p>\n $j.address.postalCode = “84726”\n <\/p>\n PS C:> $j<\/p>\n firstName : John<\/p>\n lastName : Smith<\/p>\n isAlive : True<\/p>\n age : 25<\/p>\n height_cm : 167.64<\/p>\n address : @{streetAddress=21 2nd Street; city=Escalante; state=UT; postalCode=84726}\nNow, convert the custom object back to JSON…<\/p>\n PS C:> $j | ConvertTo-Json<\/p>\n {<\/p>\n “firstName”: “John”,<\/p>\n “lastName”: “Smith”,<\/p>\n “isAlive”: true,<\/p>\n “age”: 25,<\/p>\n “height_cm”: 167.64,<\/p>\n “address”: {<\/p>\n “streetAddress”: “21 2nd Street”,<\/p>\n “city”: “Escalante”,<\/p>\n “state”: “UT”,<\/p>\n “postalCode”: “84726”<\/p>\n }<\/p>\n }\n…and replace the content in the myJson.json file:<\/p>\n PS C:> $j | ConvertTo-Json | Set-Content -Path .myJson.json\nNow you’re ready to work with more complex JSON strings, such as the new Azure Gallery templates. More on that subject in another post.\nI invite you to follow the Scripting Guys on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. \nJune Blender, <\/b>senior programming writer and Microsoft Scripting Guy<\/p>\n","protected":false},"excerpt":{"rendered":" Summary: June Blender provides a primer about JSON. Honorary Scripting Guy, June Blender, here. Today I’m going to introduce you to JSON. June is a writer for the Azure Active Directory SDK. She is also a frequent contributor to the Hey, Scripting Guy! Blog and for PowerShell.org. She lives in magnificent Escalante, Utah, where she […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[56,370,3,45],"class_list":["post-1544","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-guest-blogger","tag-june-blender","tag-scripting-guy","tag-windows-powershell"],"acf":[],"blog_post_summary":" Summary: June Blender provides a primer about JSON. Honorary Scripting Guy, June Blender, here. Today I’m going to introduce you to JSON. June is a writer for the Azure Active Directory SDK. She is also a frequent contributor to the Hey, Scripting Guy! Blog and for PowerShell.org. She lives in magnificent Escalante, Utah, where she […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/1544","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=1544"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/1544\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=1544"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=1544"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=1544"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}