<!--
{
  "documentType" : "article",
  "framework" : "ObjectiveC",
  "identifier" : "/documentation/ObjectiveC/nsscriptkeyvaluecoding",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "NSScriptKeyValueCoding"
}
-->

# NSScriptKeyValueCoding

A collection of methods that provide additional capabilities for working with key-value coding.

## Discussion

Cocoa scripting takes advantage of key-value coding to get and set information in scriptable objects. The methods in this category provide additional capabilities for working with key-value coding, including getting and setting key values by index in multi-value keys and coercing (or converting) a key value. Additional methods allow the implementer of a scriptable container class to provide fast access to elements that are being referenced by name and unique ID.

Because Cocoa scripting invokes [`setValue(_:forKey:)`](/documentation/ObjectiveC/NSObject-swift.class/setValue(_:forKey:)) and [`mutableArrayValue(forKey:)`](/documentation/ObjectiveC/NSObject-swift.class/mutableArrayValue(forKey:)), changes to model objects made by AppleScript scripts are observable using automatic key-value observing.

> Note:
> In OS X 10.3 and earlier, Cocoa scripting did not invoke ``doc://com.apple.objectivec/documentation/ObjectiveC/NSObject-swift.class/setValue(_:forKey:)`` or ``doc://com.apple.objectivec/documentation/ObjectiveC/NSObject-swift.class/mutableArrayValue(forKey:)``, so automatic key-value observing notification was not always done for model object changes caused by scripts. Starting in macOS 10.4, for backward binary compatibility, if it is overridden, Cocoa invokes the now-deprecated method ``doc://com.apple.objectivec/documentation/ObjectiveC/NSObject-swift.class/takeValue(_:forKey:)`` instead of ``doc://com.apple.objectivec/documentation/ObjectiveC/NSObject-swift.class/setValue(_:forKey:)``.

## Topics

### Indexed access

[`func insertValue(Any, at: Int, inPropertyWithKey: String)`](/documentation/ObjectiveC/NSObject-swift.class/insertValue(_:at:inPropertyWithKey:))

Inserts an object at the specified index in the collection specified by the passed key.

[`func removeValue(at: Int, fromPropertyWithKey: String)`](/documentation/ObjectiveC/NSObject-swift.class/removeValue(at:fromPropertyWithKey:))

Removes the object at the specified index from the collection specified by the passed key.

[`func replaceValue(at: Int, inPropertyWithKey: String, withValue: Any)`](/documentation/ObjectiveC/NSObject-swift.class/replaceValue(at:inPropertyWithKey:withValue:))

Replaces the object at the specified index in the collection specified by the passed key.

[`func value(at: Int, inPropertyWithKey: String) -> Any?`](/documentation/ObjectiveC/NSObject-swift.class/value(at:inPropertyWithKey:))

Retrieves an indexed object from the collection specified by the passed key.

### Access by name, key, or ID

[`func insertValue(Any, inPropertyWithKey: String)`](/documentation/ObjectiveC/NSObject-swift.class/insertValue(_:inPropertyWithKey:))

Inserts an object in the collection specified by the passed key.

[`func value(withName: String, inPropertyWithKey: String) -> Any?`](/documentation/ObjectiveC/NSObject-swift.class/value(withName:inPropertyWithKey:))

Retrieves a named object from the collection specified by the passed key.

[`func value(withUniqueID: Any, inPropertyWithKey: String) -> Any?`](/documentation/ObjectiveC/NSObject-swift.class/value(withUniqueID:inPropertyWithKey:))

Retrieves an object by ID from the collection specified by the passed key.

### Coercion

[`func coerceValue(Any?, forKey: String) -> Any?`](/documentation/ObjectiveC/NSObject-swift.class/coerceValue(_:forKey:))

Uses type info from the class description and `NSScriptCoercionHandler` to attempt to convert `value` for `key` to the proper type, if necessary.

### Constants

[NSScriptKeyValueCoding Exception Names](/documentation/ObjectiveC/nsscriptkeyvaluecoding-exception-names)

Exceptions raised by key-value coding methods.

## See Also

  [Cocoa Scripting Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_intro/SAppsIntro.html#//apple_ref/doc/uid/TP40002164)

  [Key-Value Coding Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/KeyValueCoding/index.html#//apple_ref/doc/uid/10000107i)


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)