[dojo.data] add Schema API

[skinner]

Sometime in the future, when we have more time, we should consider adding a dojo.data Schema API.

Here's some brainstorming about what dojo.data.api.Schema might look like:

dojo.declare("dojo.data.api.Schema",dojo.data.api.Read,{
	//	summary:
	//		This is an abstract API that data provider implementations conform to.
	//		This file defines methods signatures and intentionally leaves all the
	//		methods unimplemented.

	getFeatures: function(){
		//	summary: 
		//		See dojo.data.api.Read.getFeatures()
		return {
			 'dojo.data.api.Read': true,
			 'dojo.data.api.Schema': true
		};
	},

	getItemClass: function(/* item */ item){
		//	summary:
		//		Given an item, this method returns the item-class of the item.  
		//		For example, in a library database there might be item-classes 
		//		like Book, Author, and Movie.  Or in an LDAP datastore, 
		//		different items might belong to item-classes like Person, 
		//		Group, Organization, and Country.
		//		An item-class may be represented by a string, like "Book"; or
		//		by object with information about that item-class,
		//		like {name:"Book", attributes:["title", "author"]}; or by a 
		//		special item that holds all the information about that item-class.
		//	examples:
		//		var itemClass = store.getItemClass(item);
		//		var movie = store.getItemClass(starWars);
		//		var book = store.getItemClass(theHobbit);
		//		var person = store.getItemClass(jrrTolkien);
		dojo.unimplemented('dojo.data.api.Schema.getItemClass');
		return itemClass; // itemClass
	},
	
	getItemClasses: function(){
		//	summary:
		//		Returns an array with all the item-classes that may occur in
		//		this datastore.
  		//	examples:
		//		var array = store.getItemClasses(); // [movie, book, person]
		dojo.unimplemented('dojo.data.api.Schema.getItemClasses');
		return array; // Array of item-classes
	},

	getAttributesOfItemClass: function(/* itemClass */ itemClass){
		//	summary:
		//		Returns an array with the attributes that this class of item has.
		//	examples:
		//		var array = store.getAttributesOfItemClass(book); // [title, author]
		//		var array = store.getAttributesOfItemClass(person); // [name, dateOfBirth]
		dojo.unimplemented('dojo.data.api.Schema.getAttributesOfItemClass');
		return array; // Array of attributes
	},
	
	getTypeOfAttribute: function(/* attribute || attribute-name-string */ attribute){
		//	summary:
		//		Returns the type that an attribute normally holds.  The type
		//		may be a literal type like String or Date, or an item-class like
		//		Book or Person.
		//	issue:
		//		At some point we might also want more nuanced types for literals.
		//		We might want to specify JavaScript number literals like 
		//		"Number:int" or "Number:float", or string literals like 
		//		"String:URL".  Or, more importantly, we may need to be able to
		//		interoperate with existing databases without losing native type
		//		information.  When talking to an RDBMS, it may be important to
		//		for an app's user interface to be able to distinguish between
		//		"String:varchar(255)" and a "String:text".  Or, when talking to
		//		an XML database, it may be important to be able to use any of 
		//		the dozens of XML Schema datatypes like "float", "unsignedInt", 
		//		"year", and "uriReference".
		//	examples:
		//		var type = store.getTypeOfAttribute(title); // String
		//		var type = store.getTypeOfAttribute(publicationDate); // Date
		//		var type = store.getTypeOfAttribute(author); // Person
		dojo.unimplemented('dojo.data.api.Schema.getTypeOfAttribute');
		return type; // Object
	},
});

[skinner]

We might also want to have these methods:

getLabelAttributes: function(/* itemClass */ itemClass){
	return array; // Array of attributes
}

getIdentityAttributes: function(/* itemClass */ itemClass){
	return array; // Array of attributes
}

[skinner]

Replying to skinner:

We might also want to have these methods:
getLabelAttributes: function(/* itemClass */ itemClass)
getIdentityAttributes: function(/* itemClass */ itemClass)

Oops, those method names would conflict with the method names that we've already defined in dojo.data.api.Read. I guess we'd need to come up with something different. Maybe something like these names, only less verbose:

getLabelAttributesForItemClass: function(/* itemClass */ itemClass){
	return array; // Array of attributes
}

getIdentityAttributesForItemClass: function(/* itemClass */ itemClass){
	return array; // Array of attributes
}

[alex]

Milestone 2.0 deleted

[kriszyp]

I would think that a schema could be just per store instead of per item. This would simplify the design. Could the schema info be returned as a regular item or JS object so you don't have to have entire API just for accessing the attributes of the schema/class? That seems like terrible overkill, and an unnecessary burden on implementors. Also, why would wouldn't getItemClass be simply called getItemSchema (or getSchema if it is per store), since the API is called Schema... Or change the name of the API.

[ben hockey]

adding needsreview keyword - does anyone have any intention of doing/owning this? is there a reason to keep the ticket open?

[Adam Peller]

dojo.data is deprecated in favor of dojo.store, and I think all of these tasks have been orphaned anyway. I'd suggest closing.

[bill]

I agree with peller and neonstalwart.